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`)

ContentResolver

Resolves section JSON content into typed objects.

use JFA\FilamentCMSCore\CMS\ContentResolver;
use JFA\FilamentCMSCore\Models\Section;

$section = Section::find(1);
$content = app(ContentResolver::class)->resolve($section, pageId: 5);

Method: resolve(Section $section, ?int $pageId = null): SectionContent

SectionContent

Container for resolved block data with magic property access.

$content = $section->resolveContent();

$content->hero;           // BlockData (or NullBlockData)
$content->all('paragraph'); // BlockData[]
$content->has('hero');    // bool
$content->images;         // MediaCollection
$content->allBlocks();    // BlockData[]

Magic Access: $content->{type} returns the first block of that type.

BlockData

Wrapper for a single block’s data array.

$block = $content->hero;

$block->label;            // Field access via __get
$block->has('field');     // Check field existence
$block->toArray();        // Convert to array
$block->getSourceMap();   // Get source map array
$block->withSourceMap($map); // Return new instance with source map

NullBlockData

Safe fallback when a block type doesn’t exist. Returns null for all fields and false for has().

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;                                 // array (JSON)
$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.

SectionComponent (Livewire)

Abstract base class for frontend sections.

use JFA\FilamentCMSLivewire\Livewire\SectionComponent;

class Hero extends SectionComponent
{
    abstract protected function hydrateFromContent(SectionContent $content): void;
}

Lifecycle: mount($content) → normalize to SectionContent → hydrateFromContent() → initializeVisualEditing().

Required Methods:

abstract protected function hydrateFromContent(SectionContent $content): void

Visual Editing Hooks (called regardless, safe to override):

protected function initializeVisualEditing(): void — called after hydration; populate $cmsSourceMap here
protected function getCmsSourceMap(): array — return the source map array used by renderField()

InteractsWithVisualEditing (Trait)

Opt-in trait from franc014/ve-filament-cms-livewire. Provides editable field rendering with graceful degradation. Add it to components that need inline visual editing.

use JFA\VeFilamentCMSLivewire\Concerns\InteractsWithVisualEditing;

class Hero extends SectionComponent
{
    use InteractsWithVisualEditing;
    // Must also implement: abstract protected function resolveFieldValue(string $field): mixed
}

// 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(int $sectionId): void;

// Required by trait:
abstract protected function resolveFieldValue(string $field): mixed;

// Internal helpers:
protected function isVisualEditingActive(): bool;
protected function buildSourceMap(string $field, ...): 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`)

HasFieldLabels (Interface)

Contract for localized field labels. Optional — implement on components for better editor UX.

use JFA\VeFilamentCMSLivewire\Contracts\HasFieldLabels;

interface HasFieldLabels
{
    public function fieldLabels(): array;
}

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);

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

// Cleanup old image
$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;

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