Modulite Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require panicdevs/modulite
   php artisan vendor:publish --tag=modulite-config
   

2. Configure config/modulite.php:

   • Set enabled to true.
   • Define module_paths (e.g., ['Modules', 'App/Modules']).
   • Adjust cache_path if needed (defaults to bootstrap/cache/modulite.php).

3. Register the Plugin: Add ModulitePlugin to your Filament panel provider(s):

   use PanicDevs\Modulite\Filament\ModulitePlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(ModulitePlugin::make());
   }
   

4. First Use Case: Place a Filament panel, resource, or widget in a module (e.g., Modules/Users/Resources/UserResource). Run:

   php artisan modulite:cache
   

   Verify discovery by accessing your Filament panel—the module’s components should appear automatically.

Implementation Patterns

Core Workflows

1. Modular Development:

   • Panel Isolation: Store panel configurations in module-specific files (e.g., Modules/Admin/Panels/AdminPanel.php).
   • Shared Components: Use modulite:discover to scan for reusable widgets/pages across modules.

     php artisan modulite:discover --modules="Auth,Admin"
     

2. Performance Optimization:

   • Cache Management:
     • Development: Run modulite:cache after changes to reflect updates instantly.
     • Production: Use modulite:optimize to generate a static cache file (reduces discovery overhead).

       php artisan modulite:optimize
       

   • Layered Caching: Leverage modulite:cache:clear to invalidate specific module caches without full rebuilds.

3. Integration with Filament:

   • Dynamic Panel Registration: Use ModulitePlugin::make()->withPanels() to conditionally register panels based on module availability.

     $panel->plugin(ModulitePlugin::make()->withPanels(fn () => [
         'admin' => config('modulite.panels.admin'),
     ]));
     

   • Resource/Widget Discovery: Place resources/widgets in Modules/{Module}/Resources or Modules/{Module}/Widgets. Modulite auto-detects them.

4. Multi-Environment Setups:

   • Environment-Specific Config: Override module_paths in .env or config/modulite.php per environment (e.g., disable discovery in staging).

     'module_paths' => env('MODULE_PATHS', ['Modules']),
     

   • Partial Discovery: Use --modules flag to limit discovery to specific modules during development:

     php artisan modulite:discover --modules="Auth"
     

Advanced Patterns

1. Custom Discovery Patterns: Extend discovery logic by publishing and modifying the discovery.php config:

   'patterns' => [
       'panels' => 'Modules/*/Panels/*Panel.php',
       'resources' => 'Modules/*/Resources/*Resource.php',
       // Add custom patterns (e.g., for Spatie Media Library handlers)
       'media_handlers' => 'Modules/*/Handlers/*Handler.php',
   ],
   

   Then register a custom discovery service:

   Modulite::extend(function (Discovery $discovery) {
       $discovery->registerMediaHandlers();
   });
   

2. Event-Driven Workflows: Listen to ModuliteDiscovered and ModuliteCached events to trigger post-discovery tasks (e.g., logging, notifications):

   use PanicDevs\Modulite\Events\ModuliteDiscovered;
   
   ModuliteDiscovered::listen(function (array $discovered) {
       Log::info('Discovered modules:', $discovered);
   });
   

3. Testing:

   • Mock discovery in tests using Modulite::shouldDiscover(false):

     public function test_panel_without_discovery()
     {
         Modulite::shouldDiscover(false);
         $panel = $this->getPanel();
         // Assert no module components are registered
     }
     

   • Use Modulite::fake() to simulate cached results:

     Modulite::fake([
         'panels' => ['admin' => AdminPanel::class],
     ]);
     

Gotchas and Tips

Pitfalls

1. Cache Staleness:

   • Issue: Changes to module files aren’t reflected until modulite:cache is run.
   • Fix: Use modulite:cache --watch in development to auto-rebuild on file changes.
   • Production Note: Ensure modulite:optimize is part of your deployment script (e.g., deploy.php).

2. Circular Dependencies:

   • Issue: Modules referencing each other’s panels/resources may cause infinite loops during discovery.
   • Fix: Explicitly exclude problematic modules in config/modulite.php:

     'excluded_modules' => ['Core', 'Auth'],
     

3. Filament Version Conflicts:

   • Issue: Modulite may not support newer Filament versions immediately.
   • Fix: Check the GitHub Issues for compatibility notes. Use composer require panicdevs/modulite:dev-main for bleeding-edge support.

4. Overzealous Discovery:

   • Issue: Discovery scans all module_paths, slowing down boot time.
   • Fix: Limit paths or use modulite:discover --modules to target specific modules.

5. Plugin Registration Order:

   • Issue: ModulitePlugin must be registered after Filament’s core plugins but before custom plugins.
   • Fix: Order plugins in panel() method:

     $panel->plugin(
         FilamentCorePlugin::make(),
         ModulitePlugin::make(), // <-- Critical position
         CustomPlugin::make(),
     );
     

Debugging

1. Discovery Logs: Enable verbose logging in config/modulite.php:

   'debug' => true,
   

   Check storage/logs/laravel.log for discovery paths and errors.

2. Cache Inspection:

   • View cached data:

     php artisan modulite:inspect
     

   • Clear specific caches:

     php artisan modulite:cache:clear --module="Auth"
     

3. Common Errors:

   • "Class not found": Verify the module’s autoloader is configured (e.g., composer dump-autoload).
   • "Panel not registered": Ensure the panel class follows naming conventions (e.g., *Panel.php).
   • "Permission denied": Set correct permissions for bootstrap/cache/:

     chmod -R 775 bootstrap/cache/
     

Tips

1. Development Workflow:

   • Use modulite:cache --watch to auto-rebuild caches during development.
   • Combine with Laravel’s optimize:clear for faster iterations:

     php artisan optimize:clear && php artisan modulite:cache
     

2. Production Optimization:

   • Schedule modulite:optimize during low-traffic periods:

     * * * * * cd /path-to-app && php artisan modulite:optimize >> /dev/null 2>&1
     

   • Monitor cache hits/misses with modulite:stats.

3. Extending Functionality:

   • Custom Providers: Create a service provider to extend discovery:

     public function boot()
     {
         Modulite::extend(function (Discovery $discovery) {
             $discovery->registerCustomProvider(CustomProvider::class);
         });
     }
     

   • Dynamic Module Loading: Use Modulite::loadModules() to conditionally load modules based on user roles or features.

4. Performance Tuning:

   • Exclude Unused Modules: List only active modules in module_paths to reduce scan time.
   • Cache Directory: Move cache_path to a faster storage (e.g., RAM disk):

     'cache_path' => '/dev/shm/modulite_cache.php',
     

5. Security:

   • Restrict modulite:cache commands to trusted users in app/Console/Kernel.php:

     protected $commands = [
         \PanicDevs\Modulite\Console\CacheCommand::class => ['cache'],
     ];
     

   • Validate module paths in config/modulite.php to prevent directory traversal:

     'module_paths' => [app_path('Modules')],