Filament Plugin Essentials Laravel Package

Getting Started

First Steps

1. Installation Run:

   composer require bezhansalleh/filament-plugin-essentials
   

   Publish the config (if needed) with:

   php artisan vendor:publish --provider="BezhanSalleh\FilamentPluginEssentials\FilamentPluginEssentialsServiceProvider"
   

2. Basic Setup Add the trait to your Filament plugin class:

   use BezhanSalleh\FilamentPluginEssentials\Traits\HasPluginSettings;
   use BezhanSalleh\FilamentPluginEssentials\Traits\HasPluginWidgets;
   
   class MyPlugin extends Plugin
   {
       use HasPluginSettings, HasPluginWidgets;
       // ...
   }
   

3. First Use Case: Plugin Settings Define a settings page in getSettingsPage():

   public static function getSettingsPage(): string
   {
       return MyPluginSettingsPage::route('/');
   }
   

   Create a settings page class extending SettingsPage (Filament’s built-in).

Implementation Patterns

1. Plugin Settings

• Dynamic Configuration Use HasPluginSettings to auto-register a settings page. Override getSettings() to define defaults:

  public static function getSettings(): array
  {
      return [
          'key' => 'default_value',
          'enabled' => true,
      ];
  }
  

  Access settings via plugin()->getSettings() in any plugin class.

• Validation Extend HasPluginSettings and override getSettingsValidationRules():

  public static function getSettingsValidationRules(): array
  {
      return [
          'key' => 'required|string',
          'enabled' => 'boolean',
      ];
  }
  

2. Plugin Widgets

• Widget Registration Use HasPluginWidgets to register widgets in getWidgets():

  public static function getWidgets(): array
  {
      return [
          MyWidget::class,
      ];
  }
  

  Widgets appear in Filament’s dashboard under your plugin’s section.

• Conditional Widgets Dynamically enable/disable widgets based on settings:

  public static function getWidgets(): array
  {
      $widgets = [MyWidget::class];
      if (!$this->getSettings()['enabled']) {
          $widgets = [];
      }
      return $widgets;
  }
  

3. Plugin Assets

• CSS/JS Bundling Use getPluginAssets() to register assets:

  public static function getPluginAssets(): array
  {
      return [
          'css' => ['css/my-plugin.css'],
          'js' => ['js/my-plugin.js'],
      ];
  }
  

  Assets are auto-compiled with Laravel Mix/Vite.

4. Plugin Routes

• Custom Routes Define routes in getRoutes():

  public static function getRoutes(): array
  {
      return [
          'prefix' => 'my-plugin',
          'middleware' => ['auth', 'verified'],
          'routes' => [
              'api' => __DIR__.'/../routes/api.php',
          ],
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Settings Persistence

   • Ensure getSettings() returns an array with all required keys to avoid null values in the DB.
   • Use plugin()->saveSettings() manually if modifying settings outside the settings page.

2. Widget Caching

   • Widgets are cached by Filament. Clear the cache (php artisan cache:clear) after changes to getWidgets().

3. Asset Loading Order

   • CSS/JS assets loaded in the order they’re defined in getPluginAssets(). Dependencies should be listed first.

4. Plugin Initialization

   • Avoid heavy logic in the plugin constructor. Use boot() for initialization:

     protected static function boot(): void
     {
         parent::boot();
         // Initialize here
     }
     

Debugging Tips

• Check Settings Dump settings in a widget or resource:

  dd($this->plugin()->getSettings());
  

• Asset Compilation If assets fail to load, check:
  • Mix/Vite config (webpack.mix.js or vite.config.js).
  • Published assets path (resources/views/vendor/filament-plugin-essentials/).

Extension Points

1. Custom Traits Extend the provided traits to add logic (e.g., HasPluginPermissions):

   trait HasPluginPermissions
   {
       public function getPermissions(): array
       {
           return [];
       }
   }
   

2. Event Listeners Listen to plugin events (e.g., PluginRegistered):

   public static function register(): array
   {
       return [
           Plugin::make()
               ->id('my-plugin')
               ->name('My Plugin')
               ->registerUsing(function () {
                   event(new PluginRegistered());
               }),
       ];
   }
   

3. Localization Override getPluginTranslations() to add language support:

   public static function getPluginTranslations(): array
   {
       return [
           'en' => __DIR__.'/../resources/lang/en.json',
           'fr' => __DIR__.'/../resources/lang/fr.json',
       ];
   }