Laravel Filament News Laravel Package

Getting Started

Minimal Steps to First Use Case

1. Installation:

   composer require novius/laravel-filament-news
   php artisan migrate
   

2. Register Plugin: Add NewsPlugin::make() to your AdminFilamentPanelProvider:

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

3. Access Admin Panel: Navigate to /admin (or your Filament panel URL) and locate the "News" section in the sidebar. You’ll find resources for Posts, Categories, and Tags.

4. First Use Case: Publish a Post

   • Go to Posts → Create Post.
   • Fill in the title, content (using Filament’s rich text editor), and assign categories/tags.
   • Click Save to publish.

Where to Look First

• Filament Resources: The package provides three pre-built Filament resources:
  • PostsResource (for managing news articles)
  • CategoryResource (for hierarchical content organization)
  • TagResource (for flexible metadata)
• Configuration File: Publish and review config/laravel-filament-news.php to customize route names, models, or locales.
• Frontend Routes: Run php artisan news-manager:publish-front to generate a basic NewsController and routes for public-facing content.

Implementation Patterns

Core Workflows

1. Content Management

• Posts:
  • Use Filament’s rich text editor (default) or replace it with a custom editor (e.g., TinyMCE, CKEditor) via resource customization.
  • Workflow: Draft → Publish (Filament’s built-in status management).
  • Example:

    // Extend PostResource to add custom fields
    use Novius\LaravelFilamentNews\Filament\Resources\Posts\PostResource;
    
    class CustomPostResource extends PostResource {
        public static function form(Form $form): Form {
            return parent::form($form)
                ->schema([
                    // Add a custom field
                    TextInput::make('custom_field')
                        ->required()
                        ->maxLength(255),
                ]);
        }
    }
    

• Categories:
  • Hierarchical structure (parent/child relationships) for nested content (e.g., "Product" → "v2.0 Release").
  • Listing Pages: Automatically generated for categories (configurable via front_routes_name).
• Tags:
  • Flat, many-to-many relationship with posts. Useful for metadata (e.g., #breaking, #tutorial).

2. Relationships

• Posts ↔ Categories/Tags:
  • Use Filament’s relationship managers to attach multiple categories/tags to a post.
  • Example:

    // In PostResource::table()
    ->columns([
        RelationshipManager::make('categories'),
        RelationshipManager::make('tags'),
    ])
    

• Reverse Relationships:
  • View all posts under a category or tagged with a specific term from the Category/Tag detail pages.

3. Localization

• Multi-Language Support:
  • The package uses Laravel’s built-in localization. Publish translations with:

    php artisan vendor:publish --tag="lang"
    

  • Example: Add a new locale to config/laravel-filament-news.php:

    'locales' => ['en', 'fr'],
    

4. Frontend Integration

• Public Routes:
  • Generate routes/controller with:

    php artisan news-manager:publish-front
    

  • Customize the NewsController to fetch posts/categories/tags via Eloquent:

    use Novius\LaravelFilamentNews\Models\NewsPost;
    
    public function show(NewsPost $post) {
        return view('news.post', ['post' => $post]);
    }
    

• Meta Tags:
  • Use novius/laravel-meta (included) to dynamically generate SEO tags:

    use Novius\LaravelMeta\Facades\Meta;
    
    Meta::setTitle($post->title)
        ->setDescription($post->excerpt)
        ->addMeta(['name' => 'keywords', 'content' => $post->tags->pluck('name')]);
    

Integration Tips

Extending Models

• Customize Models: Publish and modify the default models:

  php artisan vendor:publish --tag="migrations"
  

  • Example: Add a featured_image field to NewsPost:

    use Illuminate\Database\Schema\Blueprint;
    use Illuminate\Support\Facades\Schema;
    
    Schema::table('news_posts', function (Blueprint $table) {
        $table->string('featured_image')->nullable();
    });
    

• Accessors/Mutators: Add logic to models for dynamic data (e.g., reading time, excerpt generation):

  public function getExcerptAttribute() {
      return Str::limit(strip_tags($this->content), 160);
  }
  

Customizing Filament Resources

• Override Resources: Replace the default resources in config/laravel-filament-news.php:

  'resources' => [
      'post' => App\Filament\Resources\CustomPostResource::class,
  ],
  

• Add Widgets: Use Filament’s widgets to display stats (e.g., "Recent Posts") on the dashboard:

  use Novius\LaravelFilamentNews\Filament\Widgets\PostsOverview;
  
  public function getWidgets(): array {
      return [
          PostsOverview::class,
      ];
  }
  

API Endpoints

• Laravel Sanctum/Passport: If API access is needed, create a controller to expose posts/categories:

  use Novius\LaravelFilamentNews\Models\NewsPost;
  
  Route::get('/api/posts', function () {
      return NewsPost::with(['categories', 'tags'])->get();
  });
  

• Resource Controllers: Use Filament’s ResourceController as a base for API routes:

  use Filament\Resources\ResourceController;
  
  class PostApiController extends ResourceController {
      // Override methods for API-specific logic
  }
  

Performance

• Eager Loading: Optimize relationships in queries to avoid N+1:

  // In a controller or resource
  $posts = NewsPost::with(['categories', 'tags'])->get();
  

• Pagination: Use Filament’s built-in pagination for large datasets:

  // In PostResource::table()
  ->paginate(10)
  

Gotchas and Tips

Pitfalls

1. Schema Conflicts:

   • If your app already has posts, categories, or tags tables, the package’s migrations will fail. Solution:
     • Rename the package’s models/tables in config/laravel-filament-news.php:

       'models' => [
           'post' => App\Models\CustomPost::class,
       ],
       

     • Publish and modify migrations:

       php artisan vendor:publish --tag="migrations"
       

2. Filament Version Mismatch:

   • The package requires Filament 4. If you’re on Filament 3, you’ll need to upgrade (potential breaking changes). Solution:
     • Test the upgrade in a staging environment first.
     • Check Filament’s upgrade guide.

3. Missing Frontend Assets:

   • The package relies on novius/laravel-nova-translatable for assets. If you skip publishing them:

     php artisan vendor:publish --provider="Novius\LaravelNovaTranslatable\LaravelNovaTranslatableServiceProvider" --tag="public"
     

   • Symptom: Rich text editor or translations may not work. Fix: Run the above command.

4. Localization Gaps:

   • The package uses Laravel’s localization, but default translations may be incomplete. Solution:
     • Publish and extend language files:

       php artisan vendor:publish --tag="lang"
       

     • Add missing keys to resources/lang/{locale}/filament-news.php.

5. Route Conflicts:

   • If you define custom front_routes_name in the config but forget to clear routes:

     php artisan route:clear
     

   • Symptom: Routes may not update after config changes.

6. Permission Issues:

   • Filament’s default permissions may not align with your app’s roles. Solution:
     • Extend the package’s policies or use Filament’s gates:

       Gate::define('view-post', function ($user, $post) {
           return $user->can('view_any_post');
       });
       

Debugging Tips