Filament Themes Manager Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require alizharb/filament-themes-manager
   php artisan vendor:publish --tag=filament-themes-manager-config
   

2. Register Plugin in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel->plugins([
           FilamentThemesManagerPlugin::make(),
       ]);
   }
   

3. Enable Preview Middleware (optional) in bootstrap/app.php:

   ->withMiddleware(function (Middleware $middleware) {
       $middleware->web(append: [
           \Alizharb\FilamentThemesManager\Http\Middleware\ThemePreviewMiddleware::class,
       ]);
   })
   

First Use Case

Install a theme from GitHub:

php artisan theme:install username/repository --type=github --activate

Access the admin interface at System → Theme Manager in Filament to preview, activate, or manage themes.

Implementation Patterns

Core Workflows

1. Theme Installation:

   • GitHub: php artisan theme:install username/repo --type=github
   • ZIP: php artisan theme:install /path/to/theme.zip --type=zip
   • Local Directory: Place theme in base_path('themes') and auto-discover ('auto_discover' => true in config).

2. Theme Management:

   • Activate: Toggle via UI or app(ThemeManagerService::class)->setActiveTheme('slug').
   • Preview: Use /theme-preview/{slug} route or UI preview button.
   • Clone: php artisan theme:clone source-slug new-slug "New Theme" --activate.

3. Programmatic Access:

   // Get all themes
   $themes = app(ThemeManagerService::class)->getAllThemes();
   
   // Check active theme
   $activeTheme = Theme::active()->first();
   
   // Install via API
   $service->installThemeFromGitHub('username/repo');
   

Integration Tips

• Customize Theme Structure: Extend theme.json with additional metadata (e.g., supports: ["dark-mode", "rtl"]).
• Asset Compilation: Use Vite in themes with vite.config.js for optimized assets.
• Event Listeners: Hook into theme events (e.g., ThemeActivated, ThemeInstalled) for custom logic:

  // In EventServiceProvider
  protected function shouldDispatch(): array
  {
      return [
          ThemeActivated::class,
          ThemeInstalled::class,
      ];
  }
  

• Dashboard Widgets: Enable widgets in config ('widgets' => ['dashboard' => true]) to display theme stats on Filament dashboard.

Common Patterns

• Theme Validation: Override ThemeValidator to add custom rules:

  use Alizharb\FilamentThemesManager\Validators\ThemeValidator;
  
  class CustomThemeValidator extends ThemeValidator
  {
      protected function rules(): array
      {
          return array_merge(parent::rules(), [
              'theme.json' => ['required', 'json', function ($attribute, $value, $fail) {
                  if (!isset($value['custom_field'])) {
                      $fail('Custom field is required.');
                  }
              }],
          ]);
      }
  }
  

  Register in config/filament-themes-manager.php:

  'validator' => CustomThemeValidator::class,
  

• Preview Middleware: Extend middleware to add custom logic (e.g., redirect non-admin users):

  public function handle($request, Closure $next)
  {
      if (!$request->user()->can('preview-themes')) {
          abort(403);
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Ensure themes/ directory is writable (chmod -R 755 storage/framework/themes).
   • Fix: Verify storage/framework permissions or use storage_path('app/themes') in config.

2. Preview Session Expiry:

   • Preview sessions expire after 'session_duration' (default: 3600s). Users may lose unsaved work.
   • Fix: Increase duration in config or notify users via UI.

3. Asset Loading Failures:

   • Themes with incorrect theme.json paths (e.g., assets: ["css/app.css"] but file is css/app.scss) break asset compilation.
   • Fix: Validate paths in theme.json and use php artisan theme:validate.

4. Caching Conflicts:

   • Aggressive caching ('cache_duration' => 86400) may hide theme updates.
   • Fix: Clear cache after theme changes (php artisan cache:clear) or reduce duration in development.

5. Middleware Registration:

   • Forgetting to register ThemePreviewMiddleware causes preview routes to fail.
   • Fix: Add middleware to bootstrap/app.php as shown in Getting Started.

Debugging

• Enable Debug Mode:

  'debug' => env('THEME_DEBUG', true), // In config
  

  Logs theme operations to storage/logs/filament-themes-manager.log.

• Validate Theme Structure:

  php artisan theme:validate
  

  Checks for missing files, invalid JSON, and security issues.

• Check Theme Events: Listen for ThemeActivated or ThemeInstalled events to debug activation flows:

  ThemeActivated::listen(function (Theme $theme) {
      Log::info("Theme activated: {$theme->slug}");
  });
  

Configuration Quirks

1. Auto-Discovery:

   • Themes in base_path('themes') or resource_path('themes') are auto-discovered only if 'auto_discover' => true.
   • Tip: Disable auto-discover for production to enforce manual installation.

2. Protected Themes:

   • Themes listed in 'protected_themes' (e.g., ['default']) cannot be deleted via UI.
   • Tip: Use for critical themes like default or admin.

3. File Type Restrictions:

   • Customize 'allowed_file_types' to restrict uploaded files (e.g., block .php for security):

   'allowed_file_types' => ['css', 'scss', 'js', 'png', 'jpg'],
   

Extension Points

1. Custom Theme Sources:

   • Extend ThemeInstaller to support additional sources (e.g., S3, FTP):

   class S3ThemeInstaller extends ThemeInstaller
   {
       public function installFromS3(string $bucket, string $key): Theme
       {
           // Custom logic
       }
   }
   

   Register in config:

   'installers' => [
       's3' => S3ThemeInstaller::class,
   ],
   

2. Theme Events:

   • Dispatch custom events for theme lifecycle hooks:

   // In ThemeManagerService
   event(new ThemeCustomized($theme, $user));
   

   Listen globally or in a service provider.

3. Preview UI Customization:

   • Override preview banner views by publishing assets:

   php artisan vendor:publish --tag=filament-themes-manager-views
   

   Modify resources/views/vendor/filament-themes-manager/preview-banner.blade.php.

4. Validation Rules:

   • Add custom validation to ThemeValidator (see Implementation Patterns).

Performance Tips

• Cache Themes:

  'cache_duration' => 3600, // 1 hour (default)
  

  Set to 0 to disable caching (useful for development).

• Asset Compilation: Use Vite for themes to leverage Laravel Mix’s caching:

  // vite.config.js in theme
  export default defineConfig({
      build: {
          manifest: true,
          outDir: 'public/build',
      },
  });
  

• Bulk Operations: Use Theme::whereNotIn('slug', ['default'])->delete() for safe bulk deletion (avoids protected themes).