Filament Modules Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require coolsam/filament-modules
   php artisan vendor:publish --provider="Coolsam\Modules\FilamentModulesServiceProvider"
   

   Run migrations if needed (php artisan migrate).

2. First Module Creation:

   php artisan module:make Blog --filament
   

   This generates a module skeleton with Filament-specific files (Resources, Widgets, etc.) in Modules/Blog.

3. Register Module: In app/Providers/Filament/AdminPanelProvider.php, add:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->modules([
               \Modules\Blog\BlogModule::class,
           ]);
   }
   

4. First Use Case: Create a Filament resource inside the module:

   php artisan module:filament-resource Blog Post
   

   This auto-generates a resource in Modules/Blog/Resources/PostResource.php.

Implementation Patterns

Core Workflows

1. Modular Resource Management:

   • Place all Filament resources, widgets, and policies inside module-specific directories (e.g., Modules/Blog/Resources/, Modules/Blog/Widgets/).
   • Use php artisan module:filament-resource and php artisan module:filament-widget for scaffolding.

2. Module-Specific Configuration: Override Filament’s default config per module via config/filament.php in the module’s root:

   'resources' => [
       \Modules\Blog\Resources\PostResource::class,
   ],
   

3. Dependency Injection: Inject module services into Filament components:

   public function form(Form $form): Form
   {
       return $form
           ->schema([
               TextInput::make('title')
                   ->required()
                   ->maxLength(255),
           ])
           ->model(\Modules\Blog\Models\Post::class);
   }
   

4. Widget Isolation: Create module-specific widgets in Widgets/ and register them in the module’s getWidgets() method:

   public function getWidgets(): array
   {
       return [
           \Modules\Blog\Widgets\StatsOverview::class,
       ];
   }
   

5. Navigation Groups: Group Filament navigation items by module:

   public function getNavigationItems(): array
   {
       return [
           \Modules\Blog\Navigation\BlogNavigation::class,
       ];
   }
   

Integration Tips

• Shared Assets: Use module-specific asset paths (e.g., module:assets-publish Blog) for CSS/JS.
• Database Migrations: Run module-specific migrations with:

  php artisan module:migrate Blog
  

• Testing: Use php artisan module:test Blog to run module-specific tests.
• Seeding: Seed module data via php artisan module:seed Blog.

Gotchas and Tips

Common Pitfalls

1. Namespace Conflicts:

   • Ensure module namespaces (e.g., Modules\Blog\) don’t clash with global app namespaces.
   • Fix: Use unique module prefixes (e.g., App\Modules\Blog\).

2. Caching Issues:

   • Clear Filament and module caches after changes:

     php artisan filament:cache-clear
     php artisan module:cache-clear
     

3. Route Conflicts:

   • Module resources/widgets may conflict with global routes.
   • Fix: Explicitly prefix module routes in getRoutePrefix():

     public function getRoutePrefix(): string
     {
         return 'blog';
     }
     

4. Service Provider Order:

   • Register module service providers after Filament’s AdminPanelProvider in config/app.php.

5. Missing Module Dependencies:

   • If a module depends on another (e.g., Auth for permissions), ensure dependencies are loaded first:

     public function boot()
     {
         $this->loadModuleDependencies();
     }
     

Debugging Tips

• Check Module Registration: Verify modules are loaded in filament.php:

  'modules' => [
      \Modules\Blog\BlogModule::class,
  ],
  

• Log Module Events: Use module:event to debug module lifecycle:

  php artisan module:event Blog booting
  

• Inspect Published Assets: Check if module assets are published correctly:

  php artisan module:assets-publish Blog
  

Extension Points

1. Custom Module Bootstrapping: Override boot() in your module class to run logic after registration:

   public function boot()
   {
       // Register custom Filament policies
       Policy::map([
           \Modules\Blog\Models\Post::class => \Modules\Blog\Policies\PostPolicy::class,
       ]);
   }
   

2. Dynamic Module Loading: Load modules conditionally based on config or environment:

   public function getModules(): array
   {
       return config('filament.modules.enabled') ? [
           \Modules\Blog\BlogModule::class,
       ] : [];
   }
   

3. Module-Specific Middleware: Attach middleware to module routes:

   public function getRouteMiddleware(): array
   {
       return [
           \Modules\Blog\Http\Middleware\VerifyBlogAccess::class,
       ];
   }
   

4. API Resource Isolation: Use module:filament-api-resource to create API-only resources:

   php artisan module:filament-api-resource Blog PostApi
   

5. Localization: Override Filament translations per module by publishing language files:

   php artisan module:lang-publish Blog
   

   Then extend filament.php translations in Modules/Blog/lang/en/filament.php.