Themebundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require masando/edemy-theme-bundle
   

   Register the bundle in config/app.php under providers:

   Masando\eDemyThemeBundle\eDemyThemeBundle::class,
   

2. Publish Assets Publish the default theme assets (if applicable):

   php artisan vendor:publish --provider="Masando\eDemyThemeBundle\eDemyThemeBundle" --tag=public
   

3. First Use Case Use the bundle’s theme system to switch themes dynamically in a controller:

   use Masando\eDemyThemeBundle\Theme\ThemeManager;
   
   class ThemeController extends Controller
   {
       public function __construct(private ThemeManager $themeManager) {}
   
       public function switchTheme(string $themeName)
       {
           $this->themeManager->setActiveTheme($themeName);
           return redirect()->back();
       }
   }
   

4. View Integration Load the active theme in your resources/views/layouts/app.blade.php:

   @theme('header')
   @theme('content')
   @theme('footer')
   

Implementation Patterns

Theme Switching Workflow

1. Dynamic Theme Assignment Use middleware to set a theme based on user preferences or roles:

   namespace App\Http\Middleware;
   
   use Masando\eDemyThemeBundle\Theme\ThemeManager;
   use Closure;
   
   class SetUserTheme
   {
       public function __construct(private ThemeManager $themeManager) {}
   
       public function handle($request, Closure $next)
       {
           $theme = $request->user()->preferred_theme ?? 'default';
           $this->themeManager->setActiveTheme($theme);
           return $next($request);
       }
   }
   

2. Theme-Aware Routes Group routes by theme (if the bundle supports it):

   Route::prefix('admin')->middleware(['theme:admin'])->group(function () {
       // Admin-specific routes
   });
   

3. Fallback Themes Configure fallback themes in config/edemy-theme.php:

   'fallbacks' => [
       'dark' => 'default',
       'custom' => 'fallback',
   ],
   

Asset Management

• Theme-Specific Assets Override default assets by publishing theme-specific files:

  php artisan vendor:publish --tag=public --provider="Masando\eDemyThemeBundle\eDemyThemeBundle" --force
  

  Place custom CSS/JS in public/themes/{theme-name}/.

• Versioned Assets Use Laravel Mix/Vite to fingerprint theme assets:

  // webpack.mix.js
  mix.setPublicPath('public/themes/default/assets')
     .js('resources/themes/default/js/app.js', 'js')
     .sass('resources/themes/default/scss/app.scss', 'css');
  

Blade Directives

Extend the @theme directive for custom logic:

// In a service provider
Blade::directive('theme', function ($expression) {
    return "<?php echo app(\\Masando\\eDemyThemeBundle\\Theme\\ThemeManager::class)->renderTheme('{$expression}'); ?>";
});

Gotchas and Tips

Common Pitfalls

1. Asset Path Conflicts

   • Ensure theme assets are namespaced (e.g., /themes/{name}/assets/) to avoid collisions.
   • Clear cached views after publishing new assets:

     php artisan view:clear
     

2. Theme Caching Issues

   • If themes aren’t updating, clear the config cache:

     php artisan config:clear
     

   • Disable caching during development in config/edemy-theme.php:

     'cache' => env('APP_ENV') !== 'local',
     

3. Missing Theme Files

   • The bundle may throw ThemeNotFoundException if a theme directory is incomplete. Verify:
     • resources/themes/{name}/views/ exists.
     • config/themes.php includes the theme.

Debugging Tips

• Log Active Theme Add a temporary route to debug the active theme:

  Route::get('/debug-theme', function () {
      return response()->json([
          'active_theme' => app(\Masando\eDemyThemeBundle\Theme\ThemeManager::class)->getActiveTheme(),
      ]);
  });
  

• Check Theme Registration Ensure themes are registered in config/edemy-theme.php:

  'themes' => [
      'default' => [
          'path' => 'themes/default',
          'priority' => 10,
      ],
      'dark' => [
          'path' => 'themes/dark',
          'priority' => 5,
      ],
  ],
  

Extension Points

1. Custom Theme Directories Override the default theme path in the config:

   'theme_paths' => [
       resource_path('custom-themes'),
   ],
   

2. Theme Events Listen for theme-switch events (if the bundle emits them):

   // In a service provider
   event(new ThemeSwitched($oldTheme, $newTheme));
   

3. Dynamic Theme Loading Load themes on-demand (e.g., for A/B testing):

   $themeManager->loadTheme('experimental', resource_path('themes/experimental'));