Light Switch Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require awcodes/light-switch
   

   Ensure compatibility with your Filament version (check the compatibility table).

2. Publish Assets Run the publisher command to add the plugin’s views to your theme:

   php artisan vendor:publish --provider="Awcodes\LightSwitch\LightSwitchServiceProvider" --tag="light-switch-views"
   

   If using a custom theme, add the CSS source to your theme’s stylesheet:

   @source '../../../../vendor/awcodes/light-switch/resources/**/*.blade.php';
   

3. Enable the Plugin Register the plugin in your PanelProvider (e.g., app/Providers/Filament/AdminPanelProvider.php):

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Awcodes\LightSwitch\LightSwitchPlugin::make(),
           ]);
   }
   

4. First Use Case Visit your Filament auth pages (login/register). The theme toggle button will appear in the top-right corner, allowing users to switch between light, dark, or system themes.

Implementation Patterns

Core Workflow

1. Theme Persistence The plugin stores the user’s preferred theme in the session by default. Override this behavior by binding a custom resolver:

   LightSwitchPlugin::make()
       ->themeResolver(fn () => 'dark') // Hardcoded example
       // OR
       ->themeResolver(fn () => session('user_theme', 'light')) // Custom logic
   

2. Customizing the Toggle Button Modify the toggle’s appearance via CSS (target .light-switch-toggle). Example:

   .light-switch-toggle {
       --filament-icon-size: 1.2rem;
       --filament-icon-color: #fff;
   }
   

3. Extending Functionality Listen to theme changes via the theme.changed event:

   use Awcodes\LightSwitch\Events\ThemeChanged;
   
   event(new ThemeChanged('dark'));
   

4. Integrating with Filament Panels Ensure the plugin is registered after your custom theme is loaded. For Filament 4.x/5.x:

   $panel->theme(\App\Filament\Themes\CustomTheme::class);
   $panel->plugins([LightSwitchPlugin::make()]);
   

5. Standalone Usage (Non-Filament) If using Filament’s standalone packages (e.g., filament/support), publish the views and manually include the toggle in your auth layouts:

   @include('light-switch::toggle')
   

Gotchas and Tips

Pitfalls

1. Missing Custom Theme The plugin requires a custom Filament theme. If using the default theme, create one first:

   php artisan filament:install --theme
   

   Then publish the plugin views as shown in Getting Started.

2. CSS Conflicts If the toggle button doesn’t appear, verify:

   • The @source directive is correctly placed in your theme’s CSS.
   • No other CSS is overriding the .light-switch-toggle class.

3. Session vs. Cookie Storage By default, themes are stored in the session. For persistent preferences across devices, switch to cookies:

   LightSwitchPlugin::make()
       ->useCookies()
       ->cookieName('user_theme_pref');
   

4. Filament 3.x vs. 4.x/5.x

   • Filament 3.x: Use awcodes/light-switch:1.x.
   • Filament 4.x/5.x: Use awcodes/light-switch:2.x or 3.x. The plugin’s event system and API differ slightly between versions.

Debugging

• Toggle Not Working? Check the browser’s console for errors. Ensure the plugin’s JavaScript is loaded (included via Filament’s asset pipeline).

• Theme Not Switching? Verify the theme.changed event fires:

  ThemeChanged::dispatch($newTheme);
  

Extension Points

1. Custom Themes Beyond Light/Dark Extend the plugin to support additional themes (e.g., "sepia") by modifying the ThemeResolver:

   LightSwitchPlugin::make()
       ->themeResolver(fn () => request()->cookie('user_theme', 'light'))
       ->availableThemes(['light', 'dark', 'sepia']);
   

2. Localization Translate the toggle button’s labels by publishing the language files:

   php artisan vendor:publish --provider="Awcodes\LightSwitch\LightSwitchServiceProvider" --tag="light-switch-lang"
   

   Then override the translations in resources/lang/{locale}/light-switch.php.

3. Server-Side Theme Logic Use the theme.resolved event to apply server-side changes (e.g., database updates):

   ThemeResolved::listen(fn (ThemeResolved $event) => {
       // Log or sync theme to a user model
   });
   

4. Conditional Toggle Visibility Hide the toggle for specific users/groups:

   LightSwitchPlugin::make()
       ->visible(fn () => auth()->user()->can('toggle-theme'));