Theme Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json under require:

   composer require elao/theme-bundle
   

   Enable it in config/bundles.php (Symfony 4+):

   Elao\ThemeBundle\ElaoThemeBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=elao-theme-config
   

   Edit config/elao_theme.php to define:

   • Default theme
   • Theme directories (e.g., themes_path: 'themes')
   • Theme switcher routes

3. First Use Case: Basic Theme Switching

   • Place your themes in themes/ (e.g., themes/default, themes/alternative).
   • Each theme should have a config.yml (Symfony 2.x style) or config.php (Laravel-style) for theme-specific settings.
   • Use the elao_theme Twig extension to render theme-aware content:

     {{ render_theme('homepage') }}  {# Renders the homepage template from the active theme #}
     

Implementation Patterns

1. Theme-Aware Routing

• Override routes per theme by defining them in themes/{theme_name}/routing.yml (Symfony 2.x) or routes/{theme}.php (Laravel).
• Use the elao_theme service to dynamically load routes:

  $theme = $this->get('elao_theme');
  $theme->setActiveTheme('alternative');
  

2. Asset Management

• Themes can include their own CSS/JS assets. Use the elao_theme Twig functions:

  {% stylesheets
      'themes/*/css/style.css'
      filter='cssrewrite'
  %}{{ asset_url }}{% endstylesheets %}
  

• Cache-busting: Append ?v={{ theme.version }} to asset URLs for theme-specific versioning.

3. Template Inheritance

• Themes extend a base template (e.g., base.html.twig in themes/default/templates/).
• Override blocks in child themes:

  {# themes/alternative/templates/base.html.twig #}
  {% block title %}Alternative Theme{% endblock %}
  

4. Dynamic Theme Switching

• Use the ThemeSwitcher controller (if enabled in config) to let users toggle themes via a frontend UI.
• Programmatically switch themes in controllers:

  $this->get('elao_theme')->setActiveTheme('user_selected_theme');
  

5. Theme-Specific Configuration

• Merge theme configs with global configs:

  # themes/alternative/config.yml
  theme:
    color_scheme: dark
  

• Access in Twig:

  {{ theme_config.color_scheme }}
  

6. Laravel Integration Workflow

• Service Provider: Bind the bundle’s services in AppServiceProvider:

  $this->app->bind('elao_theme', function ($app) {
      return new \Elao\ThemeBundle\Service\ThemeManager($app['config']['elao_theme']);
  });
  

• Middleware: Create middleware to set the theme based on user preferences or other logic:

  public function handle($request, Closure $next) {
      $theme = $request->user()->preferred_theme ?? config('elao_theme.default_theme');
      app('elao_theme')->setActiveTheme($theme);
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2.x Bundle

   • The package is archived (2014) and assumes Symfony 2.x. For Laravel, expect quirks:
     • Twig extensions may not work out-of-the-box (wrap in Twig_Extension).
     • Symfony’s ContainerAware classes need Laravel equivalents (e.g., ContainerInterface → Illuminate\Container\Container).
   • Workaround: Fork the repo and adapt for Laravel (e.g., replace Symfony\Component\DependencyInjection with Laravel’s DI).

2. No Laravel-Specific Docs

   • Assumes Symfony’s Twig_Environment and Router. Override the ThemeManager to use Laravel’s View and Route services:

     $viewFactory = app('view.factory');
     $router = app('router');
     

3. Theme Caching Issues

   • The bundle caches theme configs/templates. Clear caches after theme updates:

     php artisan view:clear
     php artisan cache:clear
     

4. Asset Path Conflicts

   • Themes may override global assets. Use Laravel’s mix or asset() helper to avoid conflicts:

     <link href="{{ asset('themes/' ~ theme.name ~ '/css/style.css') }}" rel="stylesheet">
     

5. No Built-in Theme Preview

   • The ThemeSwitcher is basic. Extend it with Laravel’s Session or Cookie to persist user selections:

     $request->session()->put('theme', $themeName);
     

Debugging Tips

1. Check Active Theme Add a debug Twig function:

   // In a custom Twig extension
   public function getActiveTheme() {
       return app('elao_theme')->getActiveTheme();
   }
   

   Use in templates:

   {{ dump(active_theme()) }}
   

2. Verify Theme Directories Ensure themes_path in config/elao_theme.php points to a valid directory:

   'themes_path' => resource_path('themes'),
   

3. Template Not Found?

   • Laravel’s View resolver may not auto-discover themes. Manually register theme paths:

     $viewPaths = [
         resource_path('themes/' . $themeName . '/views'),
         resource_path('views'),
     ];
     $viewFactory->addLocation($viewPaths);
     

4. Config Overrides Theme configs (e.g., config.yml) are merged with global configs. Use !important in YAML to force overrides:

   theme:
     setting: value !important
   

Extension Points

1. Custom Theme Loader Extend Elao\ThemeBundle\Loader\ThemeLoader to support dynamic theme loading (e.g., from a database):

   class DatabaseThemeLoader extends ThemeLoader {
       public function load($themeName) {
           $theme = DB::table('themes')->where('name', $themeName)->first();
           return $theme ? $theme->path : null;
       }
   }
   

2. Theme Events Add Laravel events for theme switches (e.g., theme.switched):

   Event::listen('theme.switched', function ($theme) {
       Log::info("Switched to theme: {$theme->getName()}");
   });
   

3. Laravel Mix Integration Use Laravel Mix to compile theme assets:

   // mix.js
   mix.setPublicPath('themes/' + themeName + '/dist');
   mix.js('themes/' + themeName + '/src/js/app.js', 'js');
   

4. Multi-Tenant Themes Combine with Laravel’s tenancy packages to scope themes per tenant:

   $theme = app('elao_theme')->setActiveTheme(Tenant::current()->theme);