Filament Cms Laravel Package

Getting Started

First Steps

1. Installation Begin by installing via Composer:

   composer require tomatophp/filament-cms
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="TomatoPHP\FilamentCMS\FilamentCMSServiceProvider" --tag="filament-cms-config"
   php artisan vendor:publish --provider="TomatoPHP\FilamentCMS\FilamentCMSServiceProvider" --tag="filament-cms-assets"
   

2. Register the CMS Add the CMS panel to your Filament admin in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->id('admin')
           ->plugins([
               \TomatoPHP\FilamentCMS\FilamentCMSPlugin::make(),
           ]);
   }
   

3. First Use Case: Create a Page

   • Navigate to Filament CMS → Pages in the admin panel.
   • Click "Create Page" and define:
     • A slug (e.g., home).
     • A template (default or custom).
     • Content via the drag-and-drop builder.
   • Publish the page and preview it via the "Preview" button.

Implementation Patterns

Core Workflows

1. Page Management

   • Templates: Create reusable templates (e.g., home, blog-post) in resources/views/vendor/filament-cms/templates/.
   • Dynamic Content: Use Blade directives (@cms) to inject CMS content into existing views:

     @cms('home', 'hero_section')
     

   • Page Hierarchy: Organize pages with parent-child relationships for nested navigation.

2. Theme Management

   • Custom Themes: Extend the default theme by publishing assets:

     php artisan vendor:publish --provider="TomatoPHP\FilamentCMS\FilamentCMSServiceProvider" --tag="filament-cms-views"
     

   • Override Blade templates in resources/views/vendor/filament-cms/ (e.g., partials/head.blade.php).
   • CSS/JS: Add custom assets via the filament-cms.config.js file (published to public/filament-cms/).

3. Content Blocks

   • Block Types: Register custom blocks (e.g., testimonials, pricing tables) via service providers:

     FilamentCMS::registerBlockType(
         TestimonialBlock::make()
             ->schema([
                 TextInput::make('quote')->required(),
                 TextInput::make('author'),
             ])
     );
     

   • Reusable Blocks: Save blocks as snippets for reuse across pages.

4. Media Handling

   • Leverage Filament’s built-in media library (if using filament/spatie-media-library) for image uploads.
   • Use the Media Picker in content blocks to embed images/videos.

5. SEO & Metadata

   • Configure SEO fields (title, description, meta tags) per page via the "SEO" tab in the page editor.
   • Use the getMetaTags() method in custom templates to dynamically fetch metadata.

Integration Tips

• Filament Resources: Sync CMS pages with custom resources for extended functionality:

  public static function getPages(): array
  {
      return FilamentCMS::getPages()->where('status', 'published')->get();
  }
  

• Frontend Routing: Use Laravel’s routing to serve CMS pages:

  Route::get('/{page}', [CMSController::class, 'show'])->name('cms.page');
  

• Localization: Enable multi-language support via Filament’s localization features and translate CMS content blocks.

Gotchas and Tips

Common Pitfalls

1. Caching Issues

   • Clear Filament and CMS caches after template/theme updates:

     php artisan filament:cache:clear
     php artisan cache:clear
     

   • Debug Tip: Disable caching in filament-cms.php ('cache_enabled' => false) during development.

2. Template Overrides

   • Ensure custom templates extend the base template (@extends('filament-cms::layouts.app')) to avoid missing layouts.
   • Gotcha: Forgetting to publish views before overriding them will result in blank pages.

3. Block Schema Conflicts

   • Avoid naming conflicts when registering custom blocks (e.g., duplicate handle() values).
   • Fix: Use unique handles like custom_testimonial_block.

4. Media Permissions

   • If using Spatie’s media library, ensure the CMS user has permissions to upload media:

     FilamentCMS::configureMediaLibrary(function (MediaLibraryManager $manager) {
         $manager->allowedFileTypes(['jpg', 'png', 'pdf']);
     });
     

5. Frontend Asset Loading

   • Custom JS/CSS may not load if not properly enqueued. Use the filament-cms.config.js file for global scripts:

     window.FilamentCMSConfig = {
         scripts: [
             '/custom-script.js',
         ],
         styles: [
             '/custom-style.css',
         ],
     };
     

Debugging Tips

1. Log CMS Events Enable logging for CMS events in filament-cms.php:

   'logging' => [
       'enabled' => true,
       'channel' => 'single',
   ],
   

   Check logs at storage/logs/filament-cms.log.

2. Template Debugging Use Blade’s @debug directive to inspect variables:

   @cms('home', 'content')
   @debug(get_defined_vars())
   

3. Database Quirks

   • Run php artisan migrate if the filament_cms_pages table is missing.
   • Reset Test Data: Use php artisan filament-cms:reset to wipe test pages/blocks.

Extension Points

1. Custom Page Models Extend the default Page model:

   class CustomPage extends \TomatoPHP\FilamentCMS\Models\Page
   {
       protected $casts = [
           'is_featured' => 'boolean',
       ];
   }
   

   Register it in FilamentCMSServiceProvider:

   FilamentCMS::usePageModel(CustomPage::class);
   

2. Hooks & Events Listen to CMS events (e.g., PageSaved):

   FilamentCMS::listen('page.saved', function ($page) {
       // Send analytics or update search index
   });
   

3. API Endpoints Expose CMS data via Laravel API routes:

   Route::get('/api/cms/pages', [CMSController::class, 'apiIndex']);
   

4. Headless Mode Disable the Filament admin UI and use the CMS as a headless backend:

   FilamentCMS::headless(true);