Themer Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mrdejong/themer
   

   Add to config/app.php under providers:

   'providers' => [
       // ...
       Themer\ThemerServiceProvider::class,
   ],
   

2. Publish Config:

   php artisan vendor:publish --provider="Themer\ThemerServiceProvider"
   

   Locate config at config/themer.php.

3. First Use Case: Define a theme in config/themer.php:

   'themes' => [
       'default' => [
           'name' => 'Default Theme',
           'path' => base_path('resources/themes/default'),
       ],
       'dark' => [
           'name' => 'Dark Theme',
           'path' => base_path('resources/themes/dark'),
       ],
   ],
   

   Load a theme in a controller/middleware:

   use Themer\Facades\Themer;
   
   Themer::setTheme('dark');
   

Implementation Patterns

Core Workflows

1. Theme Switching:

   • Use middleware to set theme per route:

     public function handle($request, Closure $next) {
         Themer::setTheme('dark');
         return $next($request);
     }
     

   • Dynamically switch via user preference (e.g., stored in session or user model):

     Themer::setTheme(auth()->user()->preferred_theme ?? 'default');
     

2. Asset Overrides:

   • Override CSS/JS per theme by structuring files in:

     resources/themes/{theme}/
         ├── css/
         │   └── app.css
         ├── js/
         │   └── app.js
     

   • Use Blade directives to load theme-specific assets:

     @themer_css('app')
     @themer_js('app')
     

3. View Overrides:

   • Override Blade views per theme by mirroring Laravel’s resources/views structure:

     resources/themes/{theme}/
         ├── layouts/
         │   └── app.blade.php
         ├── partials/
         │   └── header.blade.php
     

   • Use @include with theme-aware paths:

     @include('themer::layouts.app')
     

4. Fallback Logic:

   • Configure fallback themes in config/themer.php:

     'fallback' => ['default', 'light'],
     

   • Themer will automatically fall back if a theme’s file is missing.

Integration Tips

• Blade Directives: Register custom directives in AppServiceProvider for theme-specific logic:

  Blade::directive('themer_meta', function ($expression) {
      return "<?php echo Themer::metaTag($expression); ?>";
  });
  

  Usage:

  @themer_meta('theme-color', '#333')
  

• Dynamic Theme Detection: Detect user preferences (e.g., browser prefers-color-scheme) and set theme:

  $theme = request()->header('prefers-color-scheme') === 'dark' ? 'dark' : 'default';
  Themer::setTheme($theme);
  

• Theme-Aware Assets: Use Laravel Mix/Vite to compile theme-specific assets:

  // vite.config.js
  export default defineConfig({
      build: {
          rollupOptions: {
              input: {
                  dark: path.resolve(__dirname, 'resources/themes/dark/js/app.js'),
                  default: path.resolve(__dirname, 'resources/themes/default/js/app.js'),
              },
          },
      },
  });
  

Gotchas and Tips

Pitfalls

1. Caching Issues:

   • Clear views/cache after adding new themes:

     php artisan view:clear
     php artisan cache:clear
     

   • Ensure config/themer.php cache setting is false during development:

     'cache' => env('THEMER_CACHE', false),
     

2. File Structure Sensitivity:

   • Themer expects exact directory mirroring of resources/views. Misplaced files (e.g., resources/themes/default/views/layouts/app.blade.php instead of resources/themes/default/layouts/app.blade.php) will fail silently.

3. Middleware Order:

   • Place theme-setting middleware before ShareErrorsFromSession to avoid flash messages breaking theme logic.

4. Asset Paths:

   • Hardcoded asset paths (e.g., <link href="/css/app.css">) will break. Always use:

     @themer_css('app')
     

Debugging

• Enable Debug Mode: Set 'debug' => true in config/themer.php to log missing files/fallbacks to Laravel logs.

• Check Loaded Theme: Add a temporary Blade directive to debug:

  Blade::directive('debugTheme', function () {
      return "<?php echo 'Current theme: ' . Themer::getTheme(); ?>";
  });
  

  Usage:

  @debugTheme
  

Extension Points

1. Custom Theme Resolvers: Override Themer::resolveTheme() in a service provider:

   Themer::extend(function ($theme) {
       return match ($theme) {
           'user_pref' => auth()->user()->theme_preference,
           default => $theme,
       };
   });
   

2. Theme Events: Listen for theme changes via events (not natively supported; extend via events):

   // In AppServiceProvider
   event(new ThemeChanged(Themer::getTheme()));
   

3. Theme-Specific Config: Load theme-specific config by extending the package or using Laravel’s config caching:

   // config/themer.php
   'config' => [
       'dark' => 'themes.dark',
       'default' => 'themes.default',
   ],
   

   Then load dynamically:

   config(Themer::getThemeConfigKey());
   

4. Internationalization (i18n): Override language files per theme by structuring:

   resources/lang/{locale}/themes/{theme}/
       └── messages.php
   

   Load with:

   __('messages.key', [], Themer::getTheme());