Filament Settings Hub Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tomatophp/filament-settings-hub
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="TomatoPHP\FilamentSettingsHub\FilamentSettingsHubServiceProvider" --tag="filament-settings-hub-config"
   php artisan vendor:publish --provider="TomatoPHP\FilamentSettingsHub\FilamentSettingsHubServiceProvider" --tag="filament-settings-hub-migrations"
   

   Run migrations:

   php artisan migrate
   

2. Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \TomatoPHP\FilamentSettingsHub\FilamentSettingsHubPlugin::make(),
           ]);
   }
   

3. First Use Case Define a setting group in a migration or via the GUI:

   use TomatoPHP\FilamentSettingsHub\Database\SettingGroup;
   
   SettingGroup::create([
       'name' => 'App Configuration',
       'slug' => 'app-config',
       'description' => 'Global app settings',
   ]);
   

   Access settings in code:

   $value = \TomatoPHP\FilamentSettingsHub\Facades\SettingsHub::get('app-config.some_setting');
   

Implementation Patterns

Core Workflows

1. GUI-Driven Configuration

   • Use the Filament admin panel to create, edit, and manage setting groups and keys via the /settings-hub route.
   • Define settings as groups (e.g., app-config, payment-gateway) and keys (e.g., max_upload_size, stripe_api_key).

2. Dynamic Form Fields Leverage the SettingField model to define custom fields for each setting key:

   use TomatoPHP\FilamentSettingsHub\Database\SettingField;
   
   SettingField::create([
       'group_id' => 1, // app-config group
       'key' => 'max_upload_size',
       'label' => 'Max Upload Size (MB)',
       'type' => 'number',
       'default' => 10,
       'validation_rules' => 'required|min:1',
   ]);
   

3. Accessing Settings

   • Facade:

     $value = SettingsHub::get('app-config.max_upload_size');
     

   • Service Provider Binding (for dependency injection):

     $this->app->bind(SettingsHub::class, function ($app) {
         return new SettingsHub(config('filament-settings-hub'));
     });
     

4. Environment-Based Fallbacks Use the fallback config option to default to .env values:

   // config/filament-settings-hub.php
   'fallbacks' => [
       'app-config.max_upload_size' => env('MAX_UPLOAD_SIZE', 10),
   ],
   

5. Caching Enable Redis caching for performance:

   // config/filament-settings-hub.php
   'cache' => [
       'enabled' => true,
       'driver' => 'redis',
       'prefix' => 'settings_hub_',
   ],
   

Integration Tips

• Filament Policies: Restrict access to settings via Filament’s policy system:

  public static function getFilamentSettingsHubAccess(): array
  {
      return ['admin']; // Only users with 'admin' role can access
  }
  

• Event Listeners: Listen for setting updates:

  use TomatoPHP\FilamentSettingsHub\Events\SettingUpdated;
  
  SettingUpdated::listen(function (SettingUpdated $event) {
      Log::info("Setting updated: {$event->key}", $event->payload);
  });
  

• API Access: Expose settings via Laravel Sanctum/Passport:

  Route::middleware('auth:sanctum')->get('/api/settings/{group}', function (string $group) {
      return SettingsHub::getGroup($group);
  });
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If manually creating setting_groups or setting_fields tables, ensure they match the package’s schema:

     Schema::create('setting_groups', function (Blueprint $table) {
         $table->id();
         $table->string('name');
         $table->string('slug')->unique();
         $table->text('description')->nullable();
         $table->timestamps();
     });
     

   • Fix: Drop and re-run migrations if schema drifts.

2. Caching Stale Data

   • Clear cache after manual database changes:

     php artisan cache:clear
     php artisan view:clear
     

   • Tip: Use SettingsHub::forget($key) to manually invalidate a single setting.

3. Permission Denied

   • Ensure the filament-settings-hub plugin is registered in the correct panel provider.
   • Debug: Check Filament’s resources and pages for the plugin route.

4. Field Type Limitations

   • Custom field types (e.g., rich_text, color_picker) require additional setup:

     // config/filament-settings-hub.php
     'custom_field_types' => [
         'rich_text' => \TomatoPHP\FilamentSettingsHub\FieldTypes\RichTextField::class,
     ],
     

Debugging

• Log Settings Enable debug mode in config:

  'debug' => true,
  

  Logs will appear in storage/logs/laravel.log.

• Query Builder Inspect raw queries with Laravel Debugbar or Tinker:

  php artisan tinker
  >>> \TomatoPHP\FilamentSettingsHub\Database\Setting::query()->toSql();
  

• Seeding Data Use the SettingsHubSeeder for testing:

  use TomatoPHP\FilamentSettingsHub\Database\SettingGroup;
  use TomatoPHP\FilamentSettingsHub\Database\SettingField;
  
  SettingGroup::create(['name' => 'Test', 'slug' => 'test']);
  SettingField::create([
      'group_id' => 1,
      'key' => 'test_setting',
      'type' => 'text',
      'default' => 'default_value',
  ]);
  

Extension Points

1. Custom Field Types Extend the SettingFieldType interface:

   namespace App\FilamentSettingsHub;
   
   use TomatoPHP\FilamentSettingsHub\Contracts\SettingFieldType;
   
   class CustomFieldType implements SettingFieldType
   {
       public function getWidget(): string
       {
           return 'custom-widget';
       }
   
       public function getValidationRules(): array
       {
           return ['required'];
       }
   }
   

   Register in config:

   'custom_field_types' => [
       'custom' => \App\FilamentSettingsHub\CustomFieldType::class,
   ],
   

2. Override Default Views Publish and modify the package’s views:

   php artisan vendor:publish --provider="TomatoPHP\FilamentSettingsHub\FilamentSettingsHubServiceProvider" --tag="filament-settings-hub-views"
   

   Edit files in resources/views/vendor/filament-settings-hub/.

3. API Resources Create a custom API resource for settings:

   namespace App\Http\Resources;
   
   use TomatoPHP\FilamentSettingsHub\Database\SettingGroup;
   use Illuminate\Http\Resources\Json\JsonResource;
   
   class SettingGroupResource extends JsonResource
   {
       public function toArray($request)
       {
           return [
               'id' => $this->id,
               'name' => $this->name,
               'fields' => $this->fields->map(fn ($field) => [
                   'key' => $field->key,
                   'value' => SettingsHub::get("{$this->slug}.{$field->key}"),
               ]),
           ];
       }
   }
   

4. Multi-Tenant Support Scope settings by tenant using Laravel’s tenant() helper:

   $tenantId = tenant('id');
   $value = SettingsHub::where('tenant_id', $tenantId)->get('app-config.theme');