Theme Bundle Modern Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require agg/theme-bundle-modern
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Agg\ModernThemeBundle\ModernThemeBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Publish the default config (if needed):

   php bin/console modern-theme:install
   

   Update config/packages/modern_theme.yaml to define your theme structure:

   modern_theme:
       themes_dir: '%kernel.project_dir%/themes'
       default_theme: 'default'
   

3. First Use Case: Overriding Bundle Templates Create a theme directory (e.g., themes/default) and mirror the bundle’s template structure (e.g., AggModernThemeBundle:Default:index.html.twig → themes/default/AggModernThemeBundle/Default/index.html.twig). Override a template by extending it in your theme:

   {% extends 'AggModernThemeBundle:Default:index.html.twig' %}
   {% block title %}Custom Title{% endblock %}
   

Implementation Patterns

1. Theme Inheritance & Isolation

• Hierarchical Themes: Define parent-child relationships in config/packages/modern_theme.yaml:

  modern_theme:
      themes:
          - { name: 'admin', parent: 'default' }
          - { name: 'frontend', parent: 'admin' }
  

• Isolation: Use modern-theme:switch command to activate a theme:

  php bin/console modern-theme:switch frontend
  

2. Dynamic Theme Switching

• Runtime Switching: Override the ModernThemeBundle\Twig\ThemeExtension to dynamically set themes via logic (e.g., user role):

  // src/Twig/AppThemeExtension.php
  public function getTheme(): string {
      return $this->user->hasRole('ADMIN') ? 'admin' : 'default';
  }
  

• Register the extension in config/packages/twig.yaml:

  twig:
      extensions:
          - App\Twig\AppThemeExtension
  

3. Asset Management

• Theme-Specific Assets: Organize assets in themes/{theme}/assets/ and reference them in Twig:

  {{ asset('bundles/moderntheme/default/css/style.css') }}
  

• Asset Versioning: Enable Symfony’s asset versioning in config/packages/framework.yaml:

  framework:
      assets:
          version: 'unique-%kernel.environment%'
  

4. Integration with Other Bundles

• FOSUserBundle: Override FOS templates by placing them in themes/{theme}/FOSUserBundle/.
• SonataAdmin: Extend Sonata templates by mirroring its structure (e.g., themes/{theme}/SonataAdminBundle/CRUD/).

5. Custom Theme Events

• Listen to theme-switch events to trigger logic (e.g., cache clearing):

  // src/EventListener/ThemeListener.php
  public function onThemeSwitch(ThemeEvent $event) {
      $this->cacheClearer->clear($event->getTheme());
  }
  

• Register the listener in services.yaml:

  services:
      App\EventListener\ThemeListener:
          tags:
              - { name: 'kernel.event_listener', event: 'modern_theme.switch', method: 'onThemeSwitch' }
  

Gotchas and Tips

Pitfalls

1. Template Path Priority

   • The bundle prioritizes themes over bundles. If a template exists in both, the theme’s version is used. Debug missing templates by checking:

     php bin/console debug:config modern_theme
     

2. Caching Issues

   • Clear caches after switching themes or adding new templates:

     php bin/console cache:clear
     php bin/console assetic:dump --watch
     

3. Asset Path Conflicts

   • Avoid naming conflicts between themes and bundles. Use asset() with full paths:

     {{ asset('themes/default/assets/css/style.css') }}  {# Not 'bundles/...' #}
     

4. Deprecated Symfony 2 Syntax

   • The package is Symfony 2-era. For Symfony 4/5/6:
     • Use twig.config.name instead of twig.bundles.
     • Replace {{ asset_url }} with {{ asset }}.

5. Missing Documentation

   • The package lacks examples for complex use cases (e.g., dynamic theme switching). Refer to Symfony’s theming docs for gaps.

Debugging Tips

• Verify Theme Activation:

  php bin/console debug:config modern_theme
  

• Check Template Resolution:

  php bin/console debug:twig
  

• Enable Twig Debug:

  twig:
      debug: '%kernel.debug%'
  

Extension Points

1. Custom Theme Loader Override ModernThemeBundle\Loader\ThemeLoader to support non-filesystem themes (e.g., database-driven themes).

2. Theme Compiler Pass Extend ModernThemeBundle\DependencyInjection\Compiler\ThemePass to add theme-specific services.

3. Event Dispatcher Extend ModernThemeBundle\Event\ThemeEvent to add custom events (e.g., theme.validate).

4. Twig Runtime Replace ModernThemeBundle\Twig\ThemeRuntime to customize theme resolution logic.