Spatie Laravel Settings Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require filament/spatie-laravel-settings-plugin
   

   Publish the plugin's assets and config:

   php artisan vendor:publish --provider="Filament\Settings\SettingsServiceProvider"
   

2. First Use Case

   • Register the plugin in app/Providers/AppServiceProvider.php:

     use Filament\Settings\Settings;
     use Filament\Settings\SettingsGroup;
     
     public function boot(): void
     {
         Settings::registerSettingsGroups([
             SettingsGroup::make('General', 'general')
                 ->settings([
                     Settings\SettingsField::make('site_name', 'string')
                         ->label('Site Name')
                         ->required(),
                 ]),
         ]);
     }
     

   • Access the settings panel via /admin/settings (or your configured Filament admin route).

3. Where to Look First

   • Documentation: Filament Settings Plugin Docs + Spatie Laravel Settings.
   • Example: Check the resources/views/vendor/filament/settings directory for default blade templates.
   • Config: config/filament/settings.php for customization (e.g., panel placement, caching).

Implementation Patterns

Core Workflows

1. Defining Settings Groups

   • Organize settings into logical groups (e.g., General, SEO, Payments).
   • Example:

     SettingsGroup::make('SEO', 'seo')
         ->icon('heroicon-o-chart-bar')
         ->settings([
             Settings\SettingsField::make('meta_title', 'string')
                 ->label('Default Meta Title'),
             Settings\SettingsField::make('meta_description', 'textarea')
                 ->label('Default Meta Description'),
         ]);
     

2. Field Types and Validation

   • Leverage Filament’s field types (e.g., toggle, select, color, markdown_editor).
   • Add validation rules:

     SettingsField::make('max_upload_size', 'integer')
         ->label('Max Upload Size (MB)')
         ->validationRules(['min' => 1, 'max' => 50])
         ->default(10);
     

3. Dynamic Settings

   • Use livewire components or closures for dynamic fields:

     SettingsField::make('notifications_enabled', 'toggle')
         ->label('Enable Notifications')
         ->livewire([
             'callback' => fn () => [
                 'options' => ['email' => 'Email', 'sms' => 'SMS'],
             ],
         ]);
     

4. Accessing Settings in Code

   • Retrieve settings anywhere in your app:

     use Spatie\LaravelSettings\Settings;
     
     $siteName = Settings::get('general.site_name');
     

   • Cache settings for performance:

     Settings::cacheFor(minutes: 60);
     

5. Integration with Filament Resources/Pages

   • Embed settings in custom Filament pages:

     use Filament\Settings\SettingsWidget;
     
     public static function getWidgets(): array
     {
         return [
             SettingsWidget::make(),
         ];
     }
     

Advanced Patterns

• Scoped Settings: Use Settings::for() to manage environment-specific settings (e.g., Settings::for('staging')).
• Webhooks/Events: Listen for settings.updated events to trigger actions:

  event(new SettingsUpdated($group, $key, $oldValue, $newValue));
  

• Migration Helper: Generate settings migrations:

  php artisan settings:migrate
  

Gotchas and Tips

Common Pitfalls

1. Caching Issues

   • Clear cached settings after manual changes:

     php artisan settings:clear-cache
     

   • Avoid caching in development (Settings::cacheFor(null)).

2. Field Type Mismatches

   • Ensure spatie/laravel-settings and filament/spatie-laravel-settings-plugin versions are compatible.
   • Debug with:

     php artisan settings:list
     

3. Permission Denied

   • Verify the user has access to the Filament panel where settings are registered.
   • Check config/filament.php for middleware and auth settings.

4. Database Schema Conflicts

   • Run migrations after installing:

     php artisan migrate
     

   • If extending the settings table, use spatie/laravel-settings's SettingsModel events.

Debugging Tips

• Log Settings Changes: Add a listener to settings.updating:

  Settings::updating(function (Updating $event) {
      \Log::info('Setting updated:', $event->key);
  });
  

• Inspect Raw Data: Dump settings with:

  \Log::debug(Settings::all());
  

• Test Locally: Use Settings::set('general.site_name', 'Test') in AppServiceProvider@boot for quick testing.

Extension Points

1. Custom Field Types

   • Extend Filament\Settings\SettingsField to create reusable components:

     class CustomField extends SettingsField
     {
         protected static string $view = 'filament.settings.fields.custom';
     }
     

2. Override Templates

   • Publish and modify views:

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

   • Example: Edit resources/views/vendor/filament/settings/partials/settings-table.blade.php.

3. API Access

   • Expose settings via Filament’s API:

     use Filament\Settings\SettingsApiResource;
     
     Route::apiResource('settings', SettingsApiResource::class);
     

4. Multi-Tenant Support

   • Use Settings::for($tenant) with spatie/laravel-multitenancy:

     Settings::for(Tenant::current()->id)->get('general.site_name');
     

Configuration Quirks

• Panel Placement: Control where settings appear in Filament’s sidebar via:

  Settings::registerSettingsGroups([...])->inNavigationGroup('Custom Group');
  

• Disable Caching: Set cache_enabled to false in config/filament/settings.php for real-time updates.
• Fallback Values: Use default() on fields to avoid null errors:

  SettingsField::make('timeout', 'integer')->default(30);