Theme Bundle Laravel Package

Getting Started

Minimal Setup

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

   composer require sylius/theme-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Sylius\Bundle\ThemeBundle\SyliusThemeBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define themes in config/packages/sylius_theme.yaml:

   sylius_theme:
       themes:
           default: "@SyliusTheme/default"
           custom: "@AppTheme/custom"
   

3. First Use Case Override a Twig template for the default theme:

   mkdir -p templates/bundles/SyliusTheme/default/_partials
   cp vendor/sylius/theme-bundle/Resources/views/default/_partials/navbar.html.twig templates/bundles/SyliusTheme/default/_partials/
   

   Edit the copied file to customize the navbar.

Where to Look First

• Documentation: Sylius ThemeBundle Docs (check for version-specific guides).
• Default Templates: Browse vendor/sylius/theme-bundle/Resources/views/ for base templates.
• Configuration: config/packages/sylius_theme.yaml for theme paths and defaults.
• Twig Extensions: Check Sylius\Bundle\ThemeBundle\Twig\ThemeExtension for dynamic theme switching.

Implementation Patterns

1. Theme Inheritance & Overrides

• Pattern: Use @AppTheme/custom to extend @SyliusTheme/default.
• Workflow:
  1. Create a theme directory (e.g., templates/bundles/AppTheme/custom).
  2. Copy and modify templates from the parent theme (e.g., default).
  3. Reference the theme in sylius_theme.yaml:

     themes:
         custom: "@AppTheme/custom"
     

• Integration Tip: Use {{ parent() }} in Twig to inherit blocks from parent themes.

2. Dynamic Theme Switching

• Pattern: Switch themes per user, locale, or route.
• Implementation:
  • Use the ThemeExtension in Twig:

    {% set currentTheme = app.theme.getCurrentTheme() %}
    

  • Override the ThemeContext service to dynamically resolve themes:

    # config/services.yaml
    Sylius\Bundle\ThemeBundle\Resolver\ThemeResolver:
        arguments:
            $themeContext: '@app.theme_context' # Custom service
    

  • Example ThemeContext:

    class CustomThemeContext implements ThemeContextInterface {
        public function getCurrentTheme(): string {
            return request()->user() ? 'user_theme' : 'default';
        }
    }
    

3. Asset Management

• Pattern: Override CSS/JS assets per theme.
• Workflow:
  1. Place assets in public/bundles/AppTheme/custom/assets/.
  2. Reference them in Twig:

     <link rel="stylesheet" href="{{ asset('bundles/AppTheme/custom/assets/style.css') }}">
     

  3. Use Webpack Encore or Vite to bundle theme-specific assets.

4. Theme-Agnostic Components

• Pattern: Create reusable components outside theme directories.
• Implementation:
  • Store components in templates/components/ (e.g., templates/components/alert.html.twig).
  • Include them in any theme:

    {% include '@components/alert.html.twig' %}
    

5. CLI Theme Commands

• Pattern: Generate boilerplate for new themes.
• Example:

  php bin/console sylius:theme:create custom
  

  (Extend with custom commands if needed.)

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear cache after theme changes:

     php bin/console cache:clear
     

   • Use debug:config to verify theme paths:

     php bin/console debug:config sylius_theme
     

2. Template Path Priority

   • The bundle searches in this order:
     1. templates/bundles/<ThemeNamespace>/<ThemeName>/
     2. templates/bundles/SyliusTheme/<ThemeName>/
     3. Vendor defaults.
   • Fix: Ensure your theme namespace matches the config (e.g., @AppTheme/custom → templates/bundles/AppTheme/custom/).

3. Symfony 6+ Asset Component

   • If using Symfony 6+, configure assets in config/packages/sylius_theme.yaml:

     sylius_theme:
         asset_path: '%kernel.project_dir%/public/bundles'
     

   • Use {{ asset('bundles/AppTheme/custom/image.png') }} in Twig.

4. Twig parent() in Non-Inherited Templates

   • Only works in blocks that extend a parent template. Avoid calling parent() in standalone templates.

5. Locale-Specific Themes

   • Override themes per locale by appending _<locale> to the theme name (e.g., default_en, default_fr).
   • Configure in sylius_theme.yaml:

     themes:
         default_en: "@SyliusTheme/default_en"
     

Debugging Tips

• Check Active Theme:

  {{ dump(app.theme.getCurrentTheme()) }}
  

• Verify Template Paths:

  php bin/console debug:twig
  

• Enable Debug Mode: Set APP_DEBUG=true in .env to see template inheritance traces.

Extension Points

1. Custom Theme Resolver

   • Extend ThemeResolverInterface to implement logic like:
     • A/B testing themes.
     • Role-based themes.
     • Database-driven theme selection.

2. Event Listeners

   • Listen to sylius.theme.switch to log or modify theme switches:

     use Sylius\Bundle\ThemeBundle\Event\ThemeSwitchEvent;
     
     public function onThemeSwitch(ThemeSwitchEvent $event) {
         // Custom logic here
     }
     

3. Theme Configuration

   • Override the ThemeConfiguration class to add theme-specific settings (e.g., color schemes).

4. Webpack/Vite Integration

   • Use sylius-theme entries in webpack.config.js:

     Encore
         .addEntry('sylius-theme-default', './assets/themes/default.js')
         .addEntry('sylius-theme-custom', './assets/themes/custom.js');
     

Pro Tips

• Theme Versioning: Use semantic versioning in theme names (e.g., v2.0) for backward compatibility.
• Atomic Design: Structure themes with atoms/, molecules/, organisms/ for scalability.
• CI/CD: Test theme changes in a staging environment before deployment.
• Sylius-Specific: If using Sylius, themes integrate with its asset pipeline (e.g., sylius_shop templates).