Filament Modules Laravel Package

Getting Started

Minimal Steps to Begin

1. Install the Package

   composer require coolsam/filament-modules
   

   Ensure nwidart/laravel-modules is installed (auto-installed via dependency).

2. Configure Laravel Modules Follow Laravel Modules docs to set up module autoloading in composer.json:

   "extra": {
       "merge-plugin": {
           "include": ["Modules/*/composer.json"]
       }
   }
   

   Run:

   php artisan modules:install
   

3. Register the ModulesPlugin In your AdminPanelProvider (or relevant panel provider):

   use Coolsam\Modules\ModulesPlugin;
   
   public function panel(Panel $panel): Panel {
       return $panel
           ->plugin(ModulesPlugin::make());
   }
   

4. Create a Module

   php artisan module:make MyModule
   

5. Initialize Filament in the Module

   php artisan module:filament:install MyModule
   

   Follow prompts to configure clusters/panels.

First Use Case: Adding a Resource

Generate a resource inside your module:

php artisan module:filament:resource Post --model=App\Models\Post --cluster=MyModule

This creates a resource under Modules/MyModule/app/Filament/Clusters/MyModule/Resources/PostResource.php.

Implementation Patterns

Workflows

1. Modular Resource Development

• Cluster-Based Workflow: Use clusters to group related Filament components (e.g., PostsCluster, UsersCluster).

  php artisan module:filament:cluster PostsCluster --module=MyModule
  

  Place resources/pages/widgets inside Modules/MyModule/app/Filament/Clusters/PostsCluster/.

• Panel Isolation: Create standalone panels for modules (e.g., CMSPanel, AnalyticsPanel):

  php artisan module:filament:panel CMSPanel --module=MyModule
  

  Access via the main panel’s navigation (configurable in config/filament-modules.php).

2. Plugin Integration

• Auto-Registered Plugins: Enable auto-register-plugins: true in config/filament-modules.php to auto-load all module plugins. Override MyModulePlugin.php to customize plugin behavior (e.g., add settings):

  public function getPluggable(): array {
      return [
          FilamentSettings::make('settings', Settings::class),
      ];
  }
  

• Conditional Loading: Use shouldRegister() in MyModulePlugin to conditionally load plugins:

  public function shouldRegister(): bool {
      return config('filament-modules.enable_my_module');
  }
  

3. Shared Components

• Reusable Widgets/Pages: Create widgets/pages in one module and reuse them in others by:

  1. Publishing the module as a package (e.g., composer require my-vendor/my-module).
  2. Extending the component in the consuming module:

     use Modules\MyModule\Widgets\AnalyticsWidget;
     
     class ExtendedAnalyticsWidget extends AnalyticsWidget {
         // Override methods as needed
     }
     

• Cluster Inheritance: Extend clusters to share navigation or layouts:

  class ExtendedCluster extends Cluster {
      public function getNavigationItems(): array {
          return array_merge(
              parent::getNavigationItems(),
              [/* custom items */]
          );
      }
  }
  

4. Access Control

• Module-Specific Policies: Use CanAccessTrait in resources/pages:

  use Coolsam\Modules\CanAccessTrait;
  
  class PostResource extends Resource {
      use CanAccessTrait;
  
      public static function canAccess(): bool {
          return auth()->user()->hasRole('editor');
      }
  }
  

• Policy Integration: Attach policies to module models:

  // In MyModuleServiceProvider
  Gate::define('view-post', function (User $user, Post $post) {
      return $user->isAdmin() || $post->user_id === $user->id;
  });
  

Integration Tips

1. Configuration

• Dynamic Module Loading: Disable auto-register-plugins and manually register plugins in boot():

  public function boot() {
      if ($this->shouldLoadModule()) {
          $this->app->register(\Modules\MyModule\Providers\MyModuleServiceProvider::class);
      }
  }
  

• Cluster Navigation: Customize cluster navigation in MyModuleCluster.php:

  public function getNavigationItems(): array {
      return [
          NavigationItem::make('Posts')
              ->icon('heroicon-o-document-text')
              ->url(fn () => fn() => route('filament.my-module.posts.index')),
      ];
  }
  

2. Testing

• Module Isolation: Test modules in isolation using Laravel’s --module flag:

  php artisan test --module=MyModule
  

  Mock dependencies in MyModuleServiceProvider:

  public function register() {
      $this->app->bind(\Modules\MyModule\Contracts\PostRepository::class, function () {
          return new MockPostRepository();
      });
  }
  

• Plugin Testing: Test plugins by registering them in a temporary panel:

  public function test_plugin_registration() {
      $panel = Panel::make();
      $panel->plugin(ModulesPlugin::make());
  
      $this->assertCount(1, $panel->getPlugins());
  }
  

3. Deployment

• Module Publishing: Publish modules as Composer packages:

  composer config repositories.my-module vcs https://github.com/my-vendor/my-module.git
  composer require my-vendor/my-module
  

  Ensure composer.json includes:

  "extra": {
      "merge-plugin": {
          "include": ["vendor/my-vendor/my-module/Modules/MyModule/composer.json"]
      }
  }
  

• Environment-Specific Modules: Load modules conditionally based on environment:

  // In AppServiceProvider
  if (app()->environment('production')) {
      $this->app->register(\Modules\Analytics\Providers\AnalyticsServiceProvider::class);
  }
  

Gotchas and Tips

Pitfalls

1. Autoloading Issues:

   • Symptom: Modules not discovered after installation.
   • Fix: Ensure merge-plugin is configured in composer.json and run:

     composer dump-autoload
     

2. Cluster Navigation Conflicts:

   • Symptom: Duplicate or missing navigation items.
   • Fix: Override getNavigationItems() in MyModuleCluster.php and ensure URLs are correct:

     ->url(fn () => fn() => route('filament.my-module.cluster.resource.index'))
     

3. Plugin Registration Order:

   • Symptom: Plugins not loading or dependencies failing.
   • Fix: Manually register plugins in AdminPanelProvider with dependencies first:

     ->plugin(MyBasePlugin::make())
     ->plugin(MyModulePlugin::make())
     

4. Model Binding in Resources:

   • Symptom: Resource not binding to the correct model.
   • Fix: Explicitly set the model in the resource class:

     protected static ?string $model = \Modules\MyModule\Models\Post::class;
     

5. Panel Isolation Gaps:

   • Symptom: Cross-panel navigation broken.
   • Fix: Ensure panels.group is set in config/filament-modules.php and panels are registered:

     ->panel(MyModulePanel::make())
     

Debugging Tips

1. Log Module Loading: Add debug logs in ModulesPlugin:

   public function getId(): string {
       \Log::debug('Registering ModulesPlugin');
       return 'modules-plugin';
   }
   

2. Check Configuration: Dump the config to verify settings:

   \Log::debug(config('filament-modules'));
   

3. Verify Routes: Use php artisan route:list to check if module routes are registered. Missing routes often indicate:

   • Incorrect cluster/panel configuration.
   • Missing route() definitions in resources/pages.

4. Test Module Isolation: Temporarily disable other modules to isolate issues:

   php artisan modules:disable OtherModule
   

Extension Points

1. Custom Module Commands: Extend the package’s commands (e.g., MakeFilamentResourceCommand) by publishing and overriding:

   php artisan vendor:publish --tag="filament-modules-commands"
   

   Modify app/Console/Commands/MakeFilamentResource.php.

2. Dynamic Plugin Registration: Implement shouldRegister() in custom plugins to add