Modules Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require savannabits/filament-modules
   

   Publish the config:

   php artisan vendor:publish --provider="SavannaBits\FilamentModules\FilamentModulesServiceProvider"
   

2. Create a Module:

   php artisan module:make ModuleName
   

   This generates a module skeleton in Modules/ModuleName/ with:

   • ModuleServiceProvider (registers Filament resources/pages)
   • Module.php (metadata)
   • routes/web.php (module-specific routes)

3. First Use Case: Register a Filament resource in ModuleServiceProvider:

   public function boot(): void
   {
       Filament::register(
           \Modules\ModuleName\Resources\PostResource::class
       );
   }
   

   Enable the module in config/filament-modules.php:

   'enabled' => [
       'ModuleName',
   ],
   

Where to Look First

• Module Structure: Modules/ directory (auto-generated by module:make).
• Configuration: config/filament-modules.php (enable/disable modules, namespace settings).
• Service Provider: Each module’s ModuleServiceProvider for Filament registrations.
• Routes: Module-specific routes in Modules/{Module}/routes/web.php.
• Commands: php artisan module:list, php artisan module:enable/disable.

Implementation Patterns

Core Workflows

1. Modular Filament Resources:

   • Place resources in Modules/{Module}/Resources/.
   • Register them in the module’s ModuleServiceProvider:

     public function boot(): void
     {
         if (Modules::isEnabled('ModuleName')) { // New check in v5.2.0
             Filament::register(
                 \Modules\Blog\Resources\PostResource::class,
                 \Modules\Blog\Resources\PostResource\Pages\ManagePosts::class
             );
         }
     }
     

2. Isolated Routes:

   • Define module-specific routes in Modules/{Module}/routes/web.php:

     Route::get('/blog/posts', [\Modules\Blog\Http\Controllers\PostController::class, 'index'])->name('blog.posts.index');
     

   • Prefix routes with the module name (e.g., /blog/posts) for clarity.

3. Shared Assets:

   • Use module-assets helper to publish assets:

     $this->loadViewsFrom(__DIR__.'/Views', 'modules.blog');
     $this->publishes([
         __DIR__.'/Resources/views' => resource_path('views/vendor/modules/blog'),
     ], 'module-views');
     

4. Dependency Management:

   • Declare module dependencies in composer.json:

     "extra": {
         "modules": {
             "dependencies": ["another-module"]
         }
     }
     

   • Enable dependencies in config/filament-modules.php:

     'dependencies' => [
         'Blog' => ['Cms'],
     ],
     

5. Dynamic Module Loading:

   • Lazy-load modules via Modules::enable() in a controller/middleware:

     if (Modules::isEnabled('Blog')) { // New check in v5.2.0
         Modules::enable('Blog');
     }
     

Integration Tips

• Filament Panels:

  • Register module-specific panels in ModuleServiceProvider:

    public function boot(): void
    {
        if (Modules::isEnabled('Admin')) { // New check in v5.2.0
            Filament::registerPanel(
                \Modules\Admin\Filament\AdminPanel::class
            );
        }
    }
    

• Service Providers:

  • Bind module-specific services in ModuleServiceProvider:

    public function register(): void
    {
        if (Modules::isEnabled('Blog')) { // New check in v5.2.0
            $this->app->bind(\Modules\Blog\Contracts\PostRepository::class, \Modules\Blog\Repositories\PostRepository::class);
        }
    }
    

• Views:

  • Use module-specific view namespaces:

    @extends('modules.blog::layouts.app')
    

• Testing:

  • Mock modules in tests:

    Modules::fake();
    Modules::shouldEnable('Blog');
    

• Publishing Assets:

  • Use module:publish command:

    php artisan module:publish ModuleName --tag=config,views,assets
    

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Ensure module namespaces in Module.php match the directory structure:

     protected $namespace = 'Modules\\Blog';
     

   • Fix: Run composer dump-autoload after renaming modules.

2. Route Caching:

   • Clear route cache after adding module routes:

     php artisan route:clear
     

   • Tip: Use php artisan route:list to debug missing routes.

3. Filament Panel Registration:

   • Register panels before resources in ModuleServiceProvider:

     public function boot(): void {
         if (Modules::isEnabled('Admin')) { // New check in v5.2.0
             Filament::registerPanel(AdminPanel::class); // First!
         }
         Filament::register(PostResource::class);
     }
     

4. Module Dependencies:

   • Circular dependencies will throw errors. Use module:list --tree to visualize:

     php artisan module:list --tree
     

5. Asset Compilation:

   • Modules with Vite assets require npm run dev or npm run build in the module’s directory:

     cd Modules/Blog && npm run dev
     

6. Module Provider Registration Check:

   • New in v5.2.0: The package now checks if a module is enabled before registering its provider. Ensure your ModuleServiceProvider uses Modules::isEnabled() to avoid errors.

Debugging

1. Module Not Loading:

   • Check config/filament-modules.php for enabled modules.
   • Verify the module’s ModuleServiceProvider is registered in config/app.php.
   • Ensure Modules::isEnabled('ModuleName') returns true before registration.

2. Filament Resources Missing:

   • Ensure the resource class is registered in ModuleServiceProvider only if the module is enabled:

     if (Modules::isEnabled('Blog')) { // New check in v5.2.0
         Filament::register(PostResource::class);
     }
     

   • Check for typos in the resource class name.

3. Routes Not Found:

   • Run php artisan route:list and filter by module prefix.
   • Verify routes are defined in Modules/{Module}/routes/web.php.

4. Views Not Found:

   • Check the view namespace in @extends directives.
   • Run php artisan view:clear if views are cached.

Tips

1. Module Metadata:

   • Customize module metadata in Module.php:

     protected $description = 'Handles blog posts and comments';
     protected $author = 'Your Name';
     

2. Environment-Specific Modules:

   • Enable modules conditionally in config/filament-modules.php:

     'enabled' => env('APP_ENV') === 'local' ? ['Blog', 'Cms'] : ['Blog'],
     

3. Module Commands:

   • Create module-specific Artisan commands by extending ModuleCommand:

     use SavannaBits\FilamentModules\Console\ModuleCommand;
     
     class BlogCommand extends ModuleCommand {
         protected $signature = 'blog:seed';
         // ...
     }
     

4. Testing Modules:

   • Use Modules::fake() to isolate module tests:

     public function test_module_isolation() {
         Modules::fake();
         Modules::shouldEnable('Blog');
     
         $this->get('/blog/posts')->assertOk();
     }
     

5. Performance:

   • Disable unused modules in config/filament-modules.php to reduce autoload overhead.
   • Use Modules::disable('UnusedModule') dynamically in production.

6. Extending Core Modules:

   • Override module classes by publishing and modifying:

     php artisan module:publish Blog --tag=config
     

   • Extend the module’s ModuleServiceProvider in your app’s AppServiceProvider.

7. Localization:

   • Use module-specific language files in Modules/{Module}/Resources/lang/.
   • Load them in ModuleServiceProvider:

     public function boot(): void
     {
         if (Modules::isEnabled('Blog')) { // New check in v5.2.0
             $this->loadTranslationsFrom(__DIR__.'/Resources/lang', 'modules.blog');
         }
     }
     

8. **Namespace Retrie