Filament Fabricator Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation (Laravel 10+ / Laravel 11+ / Laravel 13+ compatible):

   composer require z3d0x/filament-fabricator
   php artisan filament-fabricator:install
   

   Register the plugin in your Panel provider:

   public function panel(Panel $panel): Panel {
       return $panel->plugins([
           FilamentFabricatorPlugin::make(),
       ]);
   }
   

   Publish assets:

   php artisan filament:assets
   

2. First Use Case (Unchanged): Create a Layout and Page Block to build a page:

   php artisan filament-fabricator:layout DefaultLayout
   php artisan filament-fabricator:block HeroSection
   

   • Edit the generated DefaultLayout class and its Blade file (resources/views/layouts/default.blade.php).
   • Define the schema for HeroSection in HeroSection::defineBlock().

3. Access the Page Builder: Navigate to the Filament admin panel to create/edit pages using the block-based editor.

Implementation Patterns

Core Workflow (Updated for Laravel 13)

1. Layouts as Templates (Unchanged):

   • Use layouts to define reusable page structures (e.g., headers, footers).
   • Example: Create a DefaultLayout with shared components like navigation or ads.

   // DefaultLayout.php
   class DefaultLayout extends Layout {
       protected static ?string $name = 'default';
   }
   

   • Customize the Blade template (resources/views/layouts/default.blade.php) to include static or dynamic content.

2. Blocks as Modular Components (Unchanged):

   • Create blocks for reusable UI elements (e.g., hero sections, testimonials).
   • Define block schemas using Filament’s Block field:

   // HeroSection.php
   public static function defineBlock(Block $block): Block {
       return $block->schema([
           TextInput::make('title')->required(),
           RichEditor::make('content'),
       ]);
   }
   

   • Use @aware(['page']) in the Blade view to access the page model.

3. Page Builder Configuration (Unchanged):

   • Customize the PageBuilder field globally or per-resource:

   PageBuilder::configureUsing(function (PageBuilder $builder) {
       $builder->blockPickerStyle(BlockPickerStyle::Modal);
       $builder->collapsible();
   });
   

4. Dynamic Data Handling (Unchanged):

   • Mutate block data before rendering:

   public static function mutateData(array $data): array {
       return ['formattedTitle' => ucfirst($data['title'])];
   }
   

   • Preload related data to avoid N+1 queries:

   public static function preloadRelatedData(Page $page, array &$blocks): void {
       Helpers::preloadRelatedModels($blocks, 'items', 'ref', Post::class);
   }
   

5. Integration with Filament Resources (Unchanged):

   • Extend the default PageResource or create custom resources:

   class CustomPageResource extends PageResource {
       public static function form(Form $form): Form {
           return $form->schema([
               PageBuilder::make('blocks')->blocks([
                   HeroSection::class,
                   TestimonialBlock::class,
               ]),
           ]);
       }
   }
   

Advanced Patterns (Updated for Laravel 13)

• Conditional Blocks (Unchanged): Restrict blocks to specific layouts using visibility rules:

  Block::make('SpecialBlock')
       ->visible(fn ($get) => $get('../layout') === 'special-layout');
  

• Shared Assets (Updated for Laravel 13): Register global scripts/styles via the facade (Laravel 13's Vite 5+ support):

  FilamentFabricator::registerScripts([
      app(Vite::class)('resources/js/app.js'),
  ]);
  

• Custom Render Hooks (Unchanged): Extend the base layout with Filament render hooks:

  @hook('filament-fabricator::head.start')
      <meta name="theme-color" content="#312e81">
  @endhook
  

Gotchas and Tips

Pitfalls (Updated for Laravel 13)

1. Migration Issues (Updated):

   • When upgrading, run the Filament upgrade tool (filament-v5) and update dependencies:

   composer require filament/upgrade:"^5.0" -W --dev
   ./vendor/bin/filament-v5
   

   • Laravel 13 Specific: Ensure your project uses PHP 8.2+ (Laravel 13 requirement). Check the CHANGELOG for breaking changes related to Laravel 13 compatibility (e.g., new validation rules, updated service container bindings).

2. Block Data Serialization (Unchanged):

   • Ensure mutateData() returns an array with valid Blade-compatible keys. Invalid keys may cause runtime errors.

3. Layout Naming Conflicts (Unchanged):

   • Avoid naming layouts or blocks with reserved keywords (e.g., base, default). Use unique prefixes like app_hero_section.

4. Asset Loading (Updated for Laravel 13):

   • Forgetting to run php artisan filament:assets after installing or updating the package will break the frontend.
   • Laravel 13 Note: If using Vite 5+, ensure your vite.config.js is properly configured for Filament assets.

5. N+1 Queries (Unchanged):

   • Always use preloadRelatedData() for blocks with relational data to optimize performance.

Debugging Tips (Updated for Laravel 13)

• Block Rendering Issues (Unchanged):

  • Verify @aware(['page']) is included in the block’s Blade file.
  • Check for typos in block class names or schema field keys.

• Configuration Overrides (Unchanged):

  • Use PageBuilder::configureUsing() in a service provider’s boot() method to ensure global settings are applied early.

• Custom Layouts (Unchanged):

  • If extending the base layout, ensure the filament-fabricator::page-blocks component is included to render blocks.

• Laravel 13 Debugging:

  • Use php artisan optimize:clear if encountering caching issues with new Laravel 13 features.
  • Check for deprecation warnings related to Laravel 13's updated service container or request handling.

Extension Points (Updated for Laravel 13)

1. Custom Block Picker (Unchanged): Override the default block picker by extending BlockPicker and binding it to the PageBuilder:

   PageBuilder::configureUsing(function (PageBuilder $builder) {
       $builder->blockPicker(MyCustomBlockPicker::make());
   });
   

2. Dynamic Layout Switching (Unchanged): Allow users to switch layouts via a dropdown in the page editor:

   Select::make('layout')
       ->options(Layout::getAvailableLayouts())
       ->reactive()
       ->afterStateUpdated(fn ($state) => $this->evaluateFieldDependencies()),
   

3. Block Dependencies (Unchanged): Use Filament’s reactive() and afterStateUpdated() to dynamically show/hide fields based on block selections:

   TextInput::make('subtitle')
       ->visible(fn ($get) => $get('show_subtitle')),
   

4. Caching (Updated for Laravel 13): Cache layout/block data for high-traffic pages (Laravel 13's improved cache API):

   public function getCachedData(): array {
       return Cache::remember("page_{$this->id}_blocks", now()->addHours(1), function () {
           return $this->blocks->toArray();
       });
   }
   

   • Laravel 13 Note: Leverage Cache::tags() for better cache organization if needed.

5. Localization (Unchanged): Support multi-language blocks by adding a locale field and translating content:

   public static function mutateData(array $data): array {
       return [
           'title' => __($data['title']),
           'content' => __($data['content']),
       ];
   }