Themes Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require hasnayeen/themes
   php artisan vendor:publish --tag="themes-assets"
   

   • For user-specific themes, add:

     php artisan vendor:publish --tag="themes-migrations"
     php artisan migrate
     

2. First Use Case:

   • Access the theme selector in your Filament panel (default location: Settings > Themes).
   • Select a theme from the dropdown and customize its colors via the provided UI.
   • Themes apply immediately to the panel.

3. Where to Look First:

   • Config File: config/themes.php (published via vendor:publish).
     • Define default theme, allowed themes, and color customization options.
   • Assets: resources/views/vendor/filament-themes/ (customize via publishing).
   • Migrations: database/migrations/[timestamp]_create_theme_preferences_table.php (if using user-specific themes).

Implementation Patterns

Core Workflows

1. Global vs. User-Specific Themes:

   • Global: Set in config/themes.php under default_theme.

     'default_theme' => 'light',
     

   • User-Specific: Store preferences in theme_preferences table (requires migrations).

     // Access user theme in Filament widgets/panels:
     $userTheme = auth()->user()->theme_preferences->theme ?? config('themes.default_theme');
     

2. Customizing Themes:

   • Color Palette: Use the ThemesWidget to adjust colors for the selected theme.

     // Override default colors in config:
     'themes' => [
         'dark' => [
             'colors' => [
                 'primary' => '#3b82f6',
                 'danger' => '#ef4444',
             ],
         ],
     ],
     

   • Dynamic Themes: Extend the package by adding new themes in the config:

     'themes' => [
         'custom' => [
             'path' => 'path/to/custom-theme-folder',
             'colors' => ['primary' => '#10b981'],
         ],
     ],
     

3. Integration with Filament Panels:

   • Panel Configuration:

     return Panel::make()
         ->id('admin')
         ->path('admin')
         ->theme(fn () => auth()->user()->theme_preferences->theme ?? 'light')
         ->discoverResources(in: app_path('Http/Controllers/Admin'))
         ->discoverPages(in: app_path('Http/Controllers/Admin/Pages'));
     

   • Widgets: Use the ThemesWidget in your Filament dashboard:

     use Hasnayeen\Themes\Widgets\ThemesWidget;
     
     public function getWidgets(): array
     {
         return [
             ThemesWidget::class,
         ];
     }
     

4. Asset Customization:

   • Publish and override assets:

     php artisan vendor:publish --tag="themes-assets" --force
     

   • Modify resources/views/vendor/filament-themes/components/theme-selector.blade.php to change the UI.

Advanced Patterns

1. Conditional Theme Application:

   • Dynamically set themes based on user roles or time of day:

     $theme = auth()->user()->is_admin ? 'admin' : (now()->hour < 6 ? 'dark' : 'light');
     Panel::make()->theme(fn () => $theme);
     

2. Theme Events:

   • Listen for theme changes (extend the package or use Filament’s events):

     // Example: Log theme changes
     event(new \Hasnayeen\Themes\Events\ThemeChanged($oldTheme, $newTheme));
     

3. Dark Mode Detection:

   • Sync with system preferences (requires JavaScript):

     // In your Filament panel's JS:
     document.documentElement.classList.toggle('dark', window.matchMedia('(prefers-color-scheme: dark)').matches);
     

Gotchas and Tips

Pitfalls

1. Asset Loading Issues:

   • Symptom: Themes not applying or broken UI.
   • Fix: Ensure assets are published and cached:

     php artisan view:clear
     php artisan cache:clear
     

   • Debug: Check resources/views/vendor/filament-themes for overrides.

2. Migration Conflicts:

   • Symptom: php artisan migrate fails due to column conflicts.
   • Fix: Manually adjust the theme_preferences table migration if extending it:

     Schema::table('theme_preferences', function (Blueprint $table) {
         $table->string('custom_color')->nullable()->after('theme');
     });
     

3. Theme Not Persisting:

   • Symptom: User-specific themes reset after logout.
   • Fix: Ensure the theme_preferences table is populated and the theme() method in Panel uses:

     ->theme(fn () => auth()->check() ? auth()->user()->theme_preferences->theme : config('themes.default_theme'))
     

4. Tailwind CSS Conflicts:

   • Symptom: Custom colors override theme colors.
   • Fix: Scope theme colors to a specific class or use !important sparingly:

     .filament-theme-dark .bg-primary {
         @apply bg-[#3b82f6];
     }
     

Debugging Tips

1. Log Theme Values:

   • Add a temporary widget to debug:

     use Filament\Widgets\Widget;
     
     class DebugThemeWidget extends Widget
     {
         protected static string $view = 'filament-themes::debug-theme';
     }
     

   • View: {{ dd(auth()->user()->theme_preferences->toArray()) }}.

2. Check Published Config:

   • Verify config/themes.php matches your expectations:

     php artisan config:clear
     php artisan config:cache
     

3. Inspect Network Requests:

   • Use browser dev tools to check if theme assets (CSS/JS) are loading:
     • Look for filament-themes.css or filament-themes.js.

Extension Points

1. Add New Themes:

   • Extend the ThemesServiceProvider or create a custom provider:

     // app/Providers/ThemesServiceProvider.php
     public function register()
     {
         $this->app->singleton(ThemesManager::class, function () {
             $manager = new ThemesManager();
             $manager->addTheme('my-theme', [
                 'path' => 'path/to/theme',
                 'colors' => ['primary' => '#8b5cf6'],
             ]);
             return $manager;
         });
     }
     

2. Custom Theme UI:

   • Override the theme selector blade file:

     php artisan vendor:publish --tag="themes-views" --force
     

   • Modify resources/views/vendor/filament-themes/components/theme-selector.blade.php.

3. API for Themes:

   • Expose theme selection via a Filament API resource:

     use Hasnayeen\Themes\Contracts\Theme;
     
     public static function getRelations(): array
     {
         return [
             'theme' => Theme::class,
         ];
     }
     

4. Theme Presets:

   • Store theme presets in the database for teams/projects:

     // Migration:
     Schema::create('theme_presets', function (Blueprint $table) {
         $table->id();
         $table->string('name');
         $table->json('colors');
         $table->timestamps();
     });