Filament Plugins Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require tomatophp/filament-plugins
   php artisan filament-plugins:install
   

   Add "merge-plugin": true to composer.json under "extra" > "laravel" to enable autoloading.

2. First Use Case: Generate a basic plugin:

   php artisan make:filament-plugin ExamplePlugin
   

   This creates a scaffold with:

   • Plugin registration (PluginServiceProvider)
   • Plugin configuration (config/example-plugin.php)
   • Plugin assets (views, JS, CSS)
   • Plugin menu item (if using Filament admin panel)

3. Where to Look First:

   • Plugin Structure: Check app/Plugins/ (default) for generated plugins.
   • Configuration: Review config/filament-plugins.php for global settings.
   • Generator Commands: Run php artisan to see available plugin-related commands (e.g., make:filament-plugin, filament-plugins:publish).

Implementation Patterns

Core Workflows

1. Plugin Development Cycle:

   • Generate: Use make:filament-plugin to scaffold a new plugin.
   • Extend: Override default templates by publishing assets:

     php artisan filament-plugins:publish --plugin=ExamplePlugin
     

   • Register: Plugins auto-register if merge-plugin is enabled. Otherwise, manually register in config/app.php under providers.

2. Integration with Filament:

   • Admin Panel: Plugins automatically add menu items if they include a MenuItem class.
   • Resources: Use filament-plugins:make-resource to generate plugin-specific Filament resources (tables, forms).
   • Widgets: Add widgets via the Widgets class in your plugin:

     public static function getWidgets(): array
     {
         return [
             \App\Plugins\ExamplePlugin\Widgets\StatsOverview::class,
         ];
     }
     

3. Dynamic Plugin Loading:

   • Lazy Loading: Plugins are loaded on-demand when accessed (e.g., via menu or URL).
   • Dependencies: Define plugin dependencies in plugin.php:

     public static function getDependencies(): array
     {
         return ['another-plugin'];
     }
     

4. Configuration Management:

   • Use config('filament-plugins.example-plugin.key') to access plugin-specific settings.
   • Publish config files for customization:

     php artisan vendor:publish --tag="filament-plugins-config"
     

Advanced Patterns

1. Plugin Hooks:

   • Extend core functionality via hooks (e.g., filament-plugins.registered):

     FilamentPlugins::hook('registered', function (Plugin $plugin) {
         // Custom logic when plugin is registered
     });
     

2. Asset Management:

   • Compile plugin-specific assets using Laravel Mix or Vite. Example webpack.mix.js:

     mix.js('resources/plugins/example-plugin/js/app.js', 'public/plugins/example-plugin/js')
          .postCss('resources/plugins/example-plugin/css/app.css', 'public/plugins/example-plugin/css', [
              //
          ]);
     

3. Database Migrations:

   • Generate migrations for plugin tables:

     php artisan filament-plugins:make-migration create_example_plugin_table --plugin=ExamplePlugin
     

4. Testing:

   • Use FilamentPlugins::fake() to mock plugins in tests:

     use TomatoPHP\FilamentPlugins\Facades\FilamentPlugins;
     
     FilamentPlugins::fake([
         ExamplePlugin::class,
     ]);
     

Gotchas and Tips

Pitfalls

1. Autoloading Issues:

   • If plugins aren’t loading, verify merge-plugin is enabled in composer.json and run:

     composer dump-autoload
     

   • Ensure plugin classes are in the correct namespace (e.g., App\Plugins\ExamplePlugin).

2. Route Conflicts:

   • Plugins generate routes under /plugins/{plugin-name}/.... Avoid naming conflicts by:
     • Using unique plugin names.
     • Overriding routes in plugin.php:

       public static function getRoutes(): array
       {
           return [
               'prefix' => 'custom-prefix',
           ];
       }
       

3. Asset Loading:

   • Plugin assets (JS/CSS) must be manually linked in your layout or via Filament’s asset management:

     FilamentPlugins::asset('example-plugin::css/app.css');
     

4. Caching:

   • Clear Filament and plugin caches after changes:

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

5. Dependency Hell:

   • Plugins with circular dependencies will fail to load. Use getDependencies() to explicitly declare requirements.

Debugging Tips

1. Enable Debug Mode:

   • Set debug to true in config/filament-plugins.php to log plugin events:

     'debug' => env('FILAMENT_PLUGINS_DEBUG', false),
     

2. Check Plugin Status:

   • Use the filament-plugins:list command to see loaded/disabled plugins:

     php artisan filament-plugins:list
     

3. Log Plugin Events:

   • Listen for plugin lifecycle events:

     FilamentPlugins::listen('loading', function (Plugin $plugin) {
         Log::debug("Loading plugin: {$plugin->getName()}");
     });
     

Extension Points

1. Custom Generators:

   • Extend the plugin generator by publishing and overriding the generator stubs:

     php artisan vendor:publish --tag="filament-plugins-generator"
     

2. Plugin Store:

   • Build a marketplace by extending the PluginRepository to fetch remote plugins:

     public static function getRemotePlugins(): array
     {
         return [
             'github:vendor/plugin-repo' => 'https://github.com/vendor/plugin-repo',
         ];
     }
     

3. UI Customization:

   • Override Filament plugin UI by publishing views:

     php artisan vendor:publish --tag="filament-plugins-views"
     

   • Modify resources/views/vendor/filament-plugins/... to change default templates.

4. API Endpoints:

   • Add plugin-specific API routes by defining them in plugin.php:

     public static function getApiRoutes(): array
     {
         return [
             'prefix' => 'api/plugins/example',
             'middleware' => ['auth:sanctum'],
         ];
     }
     

5. Localization:

   • Support multi-language plugins by publishing translations:

     php artisan vendor:publish --tag="filament-plugins-lang"
     

   • Add language files to resources/lang/vendor/filament-plugins/.