Theming Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require djaney/theming-bundle
   

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

   Djaney\ThemingBundle\ThemingBundle::class,
   

2. Define Themes Configure themes in config/theming.php:

   'themes' => [
       'base' => 'BaseThemeBundle',
       'child' => 'ChildThemeBundle',
   ],
   

3. First Use Case Override a template in ChildThemeBundle (e.g., Resources/views/base.html.twig). The bundle will automatically use the child template if it exists, falling back to the base.

Implementation Patterns

Template Inheritance

• Child Overrides Base: Place child templates in Resources/views/ of the child bundle. The bundle merges paths:

  ChildThemeBundle/Resources/views/partials/header.html.twig
  └─ BaseThemeBundle/Resources/views/partials/header.html.twig (fallback)
  

• Twig Integration: Use {{ parent() }} in child templates to inherit base logic:

  {% extends 'base.html.twig' %}
  {% block title %}{{ parent() }} - Child Theme{% endblock %}
  

Dynamic Theme Switching

• Runtime Switching: Override Djaney\ThemingBundle\ThemeResolverInterface to resolve themes dynamically (e.g., via user preference):

  public function resolveTheme(): string {
      return request()->user()->preferredTheme ?? config('theming.themes.child');
  }
  

Asset Management

• CSS/JS Overrides: Mirror asset paths in the child bundle (e.g., web/css/child.css overrides web/css/base.css).
• Webpack Encore: Use encore.setPublicPath() per theme in webpack.config.js:

  if (process.env.THEME === 'child') {
      encore.setPublicPath('/build/child');
  }
  

Twig Extensions

• Theme-Aware Extensions: Extend Djaney\ThemingBundle\Twig\ThemingExtension to add theme-specific logic:

  public function getThemeAssets(): array {
      return [
          'css' => asset(mix('css/child.css')),
          'js'  => asset(mix('js/child.js')),
      ];
  }
  

Gotchas and Tips

Pitfalls

• Caching Conflicts: Clear Twig cache after adding/removing child templates:

  php artisan cache:clear
  php artisan config:clear
  

• Path Collisions: Ensure child bundle paths exactly mirror base paths (e.g., Resources/views/layouts/ vs. Resources/views/layout/).
• Service Container: Bind custom ThemeResolverInterface before ThemingBundle loads in AppServiceProvider@register().

Debugging

• Template Not Found: Check storage/logs/laravel.log for missing file errors. Verify:
  • Child bundle is published (php artisan vendor:publish --tag=theming-config).
  • File permissions allow Twig to read child templates.
• Asset Loading: Use browser dev tools to confirm assets load from the correct theme path.

Extension Points

• Custom Resolvers: Implement ThemeResolverInterface for multi-tenancy or A/B testing:

  class TenantThemeResolver implements ThemeResolverInterface {
      public function resolveTheme(): string {
          return Tenant::current()->theme ?? config('theming.themes.base');
      }
  }
  

• Theme Events: Listen for theming.theme.resolved to log or modify theme resolution:

  event(new ThemeResolved($themeName));
  

• Fallback Logic: Override Djaney\ThemingBundle\ThemingBundle to add fallback chains (e.g., child → base → default).