Modules Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require coolsam/modules
   

   Run the Laravel Modules installation:

   php artisan modules:install
   

   Update composer.json with the merge-plugin config for autoloading:

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

2. Register the Plugin: Add ModulesPlugin to your Filament panel provider (e.g., App\Providers\Filament\AdminPanelProvider):

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

3. Initialize a Module: Create a module:

   php artisan module:make MyModule
   

   Install Filament support:

   php artisan module:filament:install MyModule
   

First Use Case

Generate a Filament Resource for a module:

php artisan module:filament:resource

Follow prompts to scaffold a resource (e.g., PostResource) in Modules/MyModule/app/Filament/Resources/.

Implementation Patterns

Workflows

1. Modular Development:

   • Develop Filament resources, pages, and widgets within modules (e.g., Modules/MyModule/app/Filament/Resources/).
   • Use clusters to group related Filament components (e.g., Modules/MyModule/app/Filament/Clusters/MyModule/).
   • Example: A BlogModule with a PostsCluster containing PostResource and DashboardPage.

2. Panel Integration:

   • Register a module-specific panel (e.g., BlogPanel) via:

     php artisan module:filament:panel
     

   • Link panels to the main panel via ModulesPlugin (configurable in config/filament-modules.php).

3. Plugin-Based Isolation:

   • Create standalone plugins for modules:

     php artisan module:filament:plugin
     

   • Plugins auto-register if auto-register-plugins is true in config.

4. Access Control:

   • Extend Coolsam\Modules\Resource/Page/Widget to enforce module-level permissions:

     use Coolsam\Modules\Resource;
     use CanAccessTrait;
     
     class PostResource extends Resource {
         use CanAccessTrait;
         // ...
     }
     

Integration Tips

• Shared Dependencies: Use module-specific service providers (e.g., Modules/MyModule/app/Providers/Filament/MyModuleServiceProvider) to bind module-specific services.
• Theme Customization: Override Filament themes per module using module:filament:theme.
• Navigation: Configure clusters.use-top-navigation to true for a cleaner UI (top-level navigation with side submenus).

Gotchas and Tips

Pitfalls

1. Autoloading Issues:

   • Forgetting merge-plugin in composer.json causes missing module classes.
   • Fix: Run composer dump-autoload after adding modules.

2. Resource Generation Bugs:

   • Older versions (pre-v5.1.0) may fail to parse model classes correctly.
   • Fix: Update to v5.1.0+ or manually specify the model class in the resource stub.

3. Panel Registration Conflicts:

   • Multiple panels with the same name clash if not namespaced properly.
   • Fix: Use unique panel names (e.g., BlogAdminPanel vs. BlogPanel).

4. Cluster vs. Direct Files:

   • Files in app/Filament/ (non-cluster) take precedence over cluster files.
   • Tip: Use clusters for logical grouping; avoid mixing paths.

Debugging

• Missing Modules: Ensure modules are enabled in config/modules.php:

  'enabled' => [
      'MyModule',
  ],
  

• Plugin Not Loading: Verify ModulesPlugin is registered in the panel and auto-register-plugins is true in config/filament-modules.php.
• Navigation Missing: Check panels.group and panels.enabled in the config.

Extension Points

1. Custom Commands: Extend the package by publishing and modifying its commands (e.g., module:filament:install):

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

2. Dynamic Registration: Override ModulesPlugin to conditionally register modules:

   public static function make(): static {
       return parent::make()
           ->registerModules(fn () => Module::enabled()->where('active', true));
   }
   

3. Access Control Logic: Extend CanAccessTrait to add custom rules:

   use Coolsam\Modules\CanAccessTrait;
   
   class CustomAccessTrait {
       use CanAccessTrait;
   
       protected function authorizeAccess(): void {
           // Custom logic (e.g., role-based)
       }
   }
   

Config Quirks

• mode Setting:
  • PLUGINS: Registers modules as Filament plugins only.
  • PANELS: Registers modules as separate panels.
  • BOTH (default): Combines both approaches.
• Cluster Paths: If clusters.enabled is false, files default to app/Filament/Resources/, etc. Disable clusters for global access.