Filament Blog Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require firefly/filament-blog
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="Firefly\FilamentBlog\FilamentBlogServiceProvider" --tag="filament-blog-config"
   php artisan vendor:publish --provider="Firefly\FilamentBlog\FilamentBlogServiceProvider" --tag="filament-blog-migrations"
   php artisan migrate
   

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Firefly\FilamentBlog\FilamentBlogPlugin::make(),
           ]);
   }
   

3. First Use Case

   • Navigate to the Blog section in Filament (default path: /admin/blog).
   • Create a draft post using the WYSIWYG editor, assign categories, and set a future publish date.
   • Preview the frontend view (ensure the package’s Blade directives are included in your layout).

Implementation Patterns

Core Workflows

1. Post Management

   • Drafting: Use the built-in rich-text editor (TinyMCE by default) for content creation.
   • Scheduling: Set published_at in the Filament form to auto-publish posts later.
   • Bulk Actions: Select multiple posts to update categories, visibility, or SEO meta tags via the table actions.

2. SEO Optimization

   • Extend the Post model’s getMetaTags() method or override the MetaTags widget in your plugin instance:

     FilamentBlogPlugin::make()
         ->metaTags(function (Post $post) {
             return [
                 'title' => "Custom Title: {$post->title}",
                 'description' => "Custom description for {$post->slug}",
             ];
         })
     

3. Frontend Integration

   • Use Blade directives to fetch posts:

     @filamentBlogPosts(
         limit: 5,
         category: 'tutorials',
         withComments: true
     )
     

   • Customize the display with the @filamentBlogPost directive for individual posts.

4. Comment System

   • Enable comments via the comments() method in the plugin config:

     'comments' => [
         'enabled' => true,
         'moderation' => true, // Require admin approval
     ]
     

   • Extend the Comment model to add custom fields (e.g., user_agent, ip_address).

5. Newsletter Integration

   • Hook into the post.published event to trigger newsletter emails:

     event(new PostPublished($post));
     

   • Use Laravel’s Mail facade or a service like Mailchimp via the NewsletterService.

Advanced Patterns

1. Custom Fields Add fields to the Post form via a service provider:

   public function boot()
   {
       FilamentBlog::extendPostForm(function (Form $form) {
           $form->fields([
               TextInput::make('custom_field')
                   ->columnSpanFull(),
           ]);
       });
   }
   

2. API Endpoints Register routes in routes/api.php:

   Route::middleware('auth:sanctum')->group(function () {
       Route::apiResource('posts', \Firefly\FilamentBlog\Http\Controllers\Api\PostController::class);
   });
   

   Extend the controller to add custom logic (e.g., pagination, filtering).

3. Webhooks for Notifications Use Laravel’s queue:work to process notifications asynchronously:

   PostPublished::dispatch($post)
       ->delay(now()->addMinutes(5)) // Delay for testing
       ->onQueue('notifications');
   

4. Multi-Author Support Override the author() relationship in the Post model:

   public function author()
   {
       return $this->belongsTo(User::class, 'author_id');
   }
   

   Update the Filament form to include an AuthorSelect field.

Gotchas and Tips

Common Pitfalls

1. Migration Conflicts

   • If you’ve customized the posts table, reset migrations before publishing:

     php artisan migrate:fresh --env=testing
     

   • Check for reserved column names (e.g., created_at, updated_at) in the package’s migrations.

2. SEO Meta Tags Not Updating

   • Clear the cache after modifying metaTags():

     php artisan cache:clear
     php artisan view:clear
     

   • Ensure the MetaTags service provider is registered in config/app.php.

3. Comments Not Appearing

   • Verify the comments table exists and the commentable relationship is set up:

     public function comments()
     {
         return $this->morphMany(Comment::class, 'commentable');
     }
     

   • Check the commentable_type and commentable_id columns in the comments table.

4. Scheduled Posts Not Publishing

   • Ensure the published_at column is nullable and indexed:

     $table->timestamp('published_at')->nullable()->index();
     

   • Run the scheduler:

     php artisan schedule:run
     

   • For testing, use now() instead of a future date.

5. Frontend Styling Issues

   • The package uses Tailwind CSS. Override styles in your resources/css/app.css:

     @layer components {
         .filament-blog-post {
             @apply bg-white p-4 rounded-lg shadow;
         }
     }
     

Debugging Tips

1. Log Post Events Add logging to the PostPublished event handler:

   public function handle(PostPublished $event)
   {
       \Log::info('Post published', ['post_id' => $event->post->id]);
   }
   

2. Check Queue Jobs Monitor failed jobs in the failed_jobs table or via Tinker:

   php artisan tinker
   >>> \Illuminate\Support\Facades\Queue::failed();
   

3. Filament Plugin Isolation If the plugin conflicts with other Filament plugins, wrap its registration in a closure:

   ->plugins([
       \Firefly\FilamentBlog\FilamentBlogPlugin::make()->configureUsing(function (FilamentBlogPlugin $plugin) {
           $plugin->disableComments(); // Example: Conditional logic
       }),
   ])
   

Extension Points

1. Custom Post Types Extend the Post model to support different content types (e.g., VideoPost, Podcast):

   class VideoPost extends Post
   {
       protected $table = 'video_posts';
   
       public function video()
       {
           return $this->morphOne(Video::class, 'videoable');
       }
   }
   

   Register a new Filament resource for the custom type.

2. Third-Party Integrations

   • Disqus/Intuit Comments: Replace the comment system by overriding the comments() relationship and adding a disqus_id column.
   • Algolia Search: Add a searchable scope to the Post model and index via Laravel Scout.

3. Localization Publish and translate the language files:

   php artisan vendor:publish --tag=filament-blog-translations
   

   Update resources/lang/en/blog.php and add new locales.

4. Testing Use the package’s test helpers in tests/Feature/BlogTest.php:

   public function test_post_creation()
   {
       $post = FilamentBlog::createPost([
           'title' => 'Test Post',
           'content' => '<p>Hello, world!</p>',
       ]);
       $this->assertDatabaseHas('posts', ['title' => 'Test Post']);
   }