Filament Ui Switcher Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require andreia/filament-ui-switcher
   

   Publish the config file:

   php artisan vendor:publish --provider="Andreia\FilamentUISwitcher\FilamentUISwitcherServiceProvider" --tag="config"
   

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

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Andreia\FilamentUISwitcher\FilamentUISwitcherPlugin::make(),
           ]);
   }
   

3. First Use Case Access the UI switcher via the ⚙️ icon in the Filament topbar. Test session-based storage by toggling options and refreshing the page.

Implementation Patterns

Core Workflows

1. Customizing UI Globally Modify config/filament-ui-switcher.php to:

   • Set default colors (primary_colors), fonts (font_families), or font sizes.
   • Enable/disable optional features (e.g., mode_switcher_enabled).

2. Database Storage Integration Extend the User model to include UI preferences:

   use Andreia\FilamentUISwitcher\Traits\HasUISwitcherPreferences;
   
   class User extends Authenticatable
   {
       use HasUISwitcherPreferences;
   }
   

   Update the config to use database storage:

   'storage' => 'database',
   

3. Dynamic Layout Switching Use the FilamentUISwitcher facade to programmatically apply settings:

   use Andreia\FilamentUISwitcher\Facades\FilamentUISwitcher;
   
   FilamentUISwitcher::setPrimaryColor('#3b82f6');
   FilamentUISwitcher::setFontFamily('Inter');
   

4. Conditional Plugin Rendering Disable the plugin for specific users/roles in the panel provider:

   ->plugins([
       FilamentUISwitcherPlugin::make()->visible(fn () => auth()->user()->isAdmin()),
   ])
   

Gotchas and Tips

Pitfalls

1. Caching Conflicts Clear Filament and view caches after changing config:

   php artisan filament:cache:clear
   php artisan view:clear
   

2. Database Storage Quirks

   • Ensure the ui_preferences table exists (migration runs automatically).
   • If using database storage, verify the user_id column in the table matches your users table.

3. Livewire Version Mismatch The plugin requires Livewire 3.x or 4.x. If using Filament 4.1+, ensure compatibility:

   composer require livewire/livewire:^3.0
   

Debugging

• Console Logs: Enable debug mode in config:

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

  Check logs for storage-related errors.

• Modal Not Appearing? Verify the plugin is registered in AdminPanelProvider and the ⚙️ icon is visible in the topbar.

Extension Points

1. Custom Colors/Fonts Extend the config arrays to add your own options:

   'primary_colors' => [
       '#3b82f6', // Default blue
       '#10b981', // Custom green
       '#8b5cf6', // Custom purple
   ],
   

2. Override Default Views Publish and modify the Blade views:

   php artisan vendor:publish --tag="filament-ui-switcher-views"
   

3. API Integration Use the facade to fetch/sync settings via API:

   $preferences = FilamentUISwitcher::getPreferences();
   FilamentUISwitcher::setPreferences($newPrefs);