API Reference

This reference covers the most important classes and interfaces from franc014/filament-cms-core, franc014/filament-cms-livewire, and franc014/ve-filament-cms-livewire.

Core CMS Package (`JFA\FilamentCMSCore`)

BlockCaster

Eloquent cast that transforms JSON to BlockCollection.

use JFA\FilamentCMSCore\CMS\BlockCaster;

// Used in ContentModel casts:
protected function casts(): array
{
    return [
        'content' => BlockCaster::class,
    ];
}

// Automatically converts JSON ↔ BlockCollection
$section->content; // BlockCollection

BlockCollection

Iterable container for resolved blocks.

use JFA\FilamentCMSCore\CMS\BlockCollection;

$collection = $section->resolve(pageId: 5);

$collection->first();           // BlockData (first block)
$collection->first('hero');     // BlockData (first hero)
$collection->all('paragraph'); // BlockData[]
$collection->has('hero');      // bool
$collection->count();          // int
$collection->isEmpty();        // bool
$collection->toArray();        // array

BlockData

Abstract base class for block data.

use JFA\FilamentCMSCore\CMS\BlockData;

$block = $collection->first('hero');

$block->get('label');        // Field access
$block->toArray();           // Convert to array
$block->getSourceMap();      // Source map array
$block->getFieldLabels();    // Labels array

GenericBlockData

Default concrete implementation of BlockData.

use JFA\FilamentCMSCore\CMS\GenericBlockData;

$block = new GenericBlockData(
    data: ['headline' => 'Hello'],
    sourceMap: ['sectionId' => 1],
    fieldLabels: ['headline' => 'Headline'],
);

$block->get('headline');    // 'Hello'

BlockRegistry

Maps block types to DTO classes.

use JFA\FilamentCMSCore\CMS\BlockRegistry;

$registry = app(BlockRegistry::class);

$registry->register('hero', HeroBlock::class);
$registry->resolve('hero');  // HeroBlock::class

BlockSchemaExtractor

Auto-extracts field labels from ContentBlock schemas.

use JFA\FilamentCMSCore\Forms\Blocks\BlockSchemaExtractor;

$labels = BlockSchemaExtractor::getLabels('hero');
// Returns: ['headline' => 'Headline', 'label' => 'Label', ...]

BlockSchemaExtractor::clearCache(); // For testing

ContentBlock (Interface)

Contract for content block definitions.

use JFA\FilamentCMSCore\Contracts\ContentBlock;

interface ContentBlock
{
    public static function make(): \Filament\Forms\Components\Builder\Block;
}

ContentBlockRegistry

Singleton resolving block schemas from config.

$registry = app(\JFA\FilamentCMSCore\Forms\Blocks\ContentBlockRegistry::class);

$registry->getAll();           // All registered blocks
$registry->getByName('hero');  // Specific block by type name

Models

Page

use JFA\FilamentCMSCore\Models\Page;

$page = Page::bySlug('about');                    // Cached lookup
$page->sections();                                 // BelongsToMany
$page->sectionsForUI();                           // Resolved sections array
$page->publish();                                  // Set published
$page->unpublish();                               // Set draft

Section

use JFA\FilamentCMSCore\Models\Section;

$section = Section::find(1);
$section->content;                                 // BlockCollection (via BlockCaster)
$section->resolve(pageId: 5);                     // BlockCollection with source maps
$section->getRawContent();                        // Raw JSON array
$section->getBlockFieldValue('hero', 'label');    // Direct field access
$section->updateBlockField('hero', 'label', 'New'); // Direct field update
$section->pages();                                 // BelongsToMany
$section->activate();                              // Set active
$section->deactivate();                           // Set inactive

Post

use JFA\FilamentCMSCore\Models\Post;

$post = Post::find(1);
$post->publish();
$post->unpublish();
$post->categories();                               // BelongsToMany

FilamentCMSCorePlugin

Plugin registration for Filament panels.

use JFA\FilamentCMSCore\FilamentCMSCorePlugin;

FilamentCMSCorePlugin::make()
    ->registerResources([
        // Auto-discovered from config
    ]);

Livewire Frontend Package (`JFA\FilamentCMSLivewire`)

Page (Livewire)

Abstract base class for frontend pages.

use JFA\FilamentCMSLivewire\Livewire\Page;

class About extends Page
{
    public function __construct()
    {
        parent::__construct(
            componentView: 'livewire.pages.about',
            slug: 'about',
            layout: 'layouts.app',
        );
    }
}

Automatically resolves CMS page and sections on render. Passes BlockCollection to section components.

SectionComponent (Livewire)

Abstract base class for frontend sections.

use JFA\FilamentCMSLivewire\Livewire\SectionComponent;

class Hero extends SectionComponent
{
    public string $label = '';
    public string $headline = '';
    public array $cmsSourceMap = [];

    // autoHydrate() handles property mapping
}

Lifecycle: mount($block) → normalize to BlockCollection → autoHydrate() → initializeVisualEditing().

Key Properties:

protected ?BlockCollection $block — The block collection (not serialized by Livewire)
public array $blockData — Raw data for Livewire serialization

Key Methods:

mount($block = []) — Accepts BlockCollection or arrays
hydrate() — Reconstructs BlockCollection after Livewire restore
autoHydrate() — Maps block data to public properties via reflection
initializeVisualEditing() — Override to set $cmsSourceMap and custom properties

InteractsWithVisualEditing (Trait)

Opt-in trait from franc014/ve-filament-cms-livewire. Provides editable field rendering with graceful degradation.

use JFA\VeFilamentCMSLivewire\Concerns\InteractsWithVisualEditing;

class Hero extends SectionComponent
{
    use InteractsWithVisualEditing;
}

// Methods provided by the trait:
public function renderField(string $field, ?string $fieldType = null, bool $escape = true): ?string;
public function renderImageField(string $field, ?string $fieldLabel = null): ?string;
public function renderRepeaterContainer(string $field, ?string $fieldLabel = null): ?string;

// Event listener — automatically refreshes content after inline edits
#[On('contentUpdated')]
public function refreshFromCMS(mixed $sectionId): void;

// Internal helpers:
protected function isVisualEditingActive(): bool;
protected function buildSourceMap(string $field, ...): array;
protected function normalizeSourceMapKeys(array $map): array;

Metatags (Trait)

Trait for injecting SEO meta tags from CMS page data.

use JFA\FilamentCMSLivewire\Traits\Metatags;

class About extends Page
{
    use Metatags;
}

Visual Editing Package (`JFA\VeFilamentCMSLivewire`)

CmsSourceMap

Immutable value object for content provenance.

use JFA\VeFilamentCMSLivewire\CmsSourceMap;

$map = new CmsSourceMap(
    sectionId: 12,
    sectionSlug: 'hero',
    blockType: 'hero',
    blockIndex: 0,
    pageId: 5,
);

$fieldMap = $map->forField('headline', 'text');
$itemMap = $map->forRepeaterItem(2);

$map->toArray();   // Array representation
$map->toJson();    // JSON string
CmsSourceMap::fromJson($json); // Reconstruct

EditingMode

Session-backed editing state manager.

use JFA\VeFilamentCMSLivewire\EditingMode;

$mode = app(EditingMode::class);

$mode->activate();      // Enable editing
$mode->deactivate();    // Disable editing
$mode->isActive();      // bool

VisualEditor (Livewire)

Floating UI component for editing mode.

use JFA\VeFilamentCMSLivewire\Livewire\VisualEditor;

// Component properties:
public bool $canEdit;
public bool $isEditing;
public bool $isModalOpen;
public array $activeSourceMap;

// Methods:
public function toggle(): void;
public function openEditor(array $sourceMap): void;
public function closePanel(): void;

Use in Blade:

<livewire:visual-editor />

InlineEditForm (Livewire)

Slide-over form for editing content.

use JFA\VeFilamentCMSLivewire\Livewire\InlineEditForm;

// Component properties:
public array $sourceMap;
public string $field;
public string $fieldType;
public string $fieldLabel;
public $section;
public array $data;

// Methods:
public function loadFromSourceMap(): void;
public function save(): void;

Use with dynamic wire:key:

<livewire:inline-edit-form
    :source-map="$activeSourceMap"
    wire:key="edit-{{ md5(json_encode($activeSourceMap)) }}"
/>

ImageUploadHandler

Handles image persistence from temporary to permanent storage.

use JFA\VeFilamentCMSLivewire\ImageUploadHandler;

$handler = app(ImageUploadHandler::class);

$path = $handler->persist(
    value: 'livewire-tmp/upload-123.jpg',
    sectionSlug: 'hero',
    oldPath: 'cms/hero/old-image.jpg'
);

$handler->cleanup('cms/hero/old-image.jpg');

RepeaterSchemaBuilder

Dynamically builds repeater form schemas.

use JFA\VeFilamentCMSLivewire\RepeaterSchemaBuilder;

$builder = app(RepeaterSchemaBuilder::class);

$repeater = $builder->build(
    blockType: 'team',
    fieldName: 'members',
    fieldLabel: 'Team Members',
    sectionSlug: 'team'
);

Enums

PageStatus

use JFA\FilamentCMSCore\Enums\PageStatus;

PageStatus::DRAFT;
PageStatus::PUBLISHED;

SectionStatus

use JFA\FilamentCMSCore\Enums\SectionStatus;

SectionStatus::ACTIVE;
SectionStatus::INACTIVE;

Helper Classes

ContentBuilder

Factory for the builder field used in section forms.

use JFA\FilamentCMSCore\Forms\ContentBuilder;

ContentBuilder::make('content');

SharedFields

Trait with common form field helpers.

use JFA\FilamentCMSCore\Forms\Components\SharedFields;

SharedFields::titleAndSlugFields();  // Title + auto-slug
SharedFields::metatagsField();       // SEO metatags KeyValue
SharedFields::urlSelector();         // URL type selector