Getting Started

Minimal Setup

Installation:

composer require deepaspl/theme-bundle

Add to config/bundles.php:

return [
    // ...
    Liip\ThemeBundle\LiipThemeBundle::class => ['all' => true],
];

Basic Configuration (config/packages/liip_theme.yaml):

liip_theme:
    themes: ['default', 'dark', 'corporate']
    active_theme: 'default'

First Use Case:
- Create a theme folder in your bundle:
```
src/YourBundle/Resources/themes/dark/
```
- Place a Twig template (e.g., src/YourBundle/Resources/themes/dark/index.html.twig) alongside the default view.
- Access via URL: /theme/switch?theme=dark (if routing is imported).

Implementation Patterns

1. Theme-Aware Bundle Structure

Organize views by theme:

src/YourBundle/Resources/
├── themes/
│   ├── default/
│   │   ├── index.html.twig
│   │   └── partials/
│   └── dark/
│       ├── index.html.twig
│       └── partials/
└── views/  # Fallback if theme not found

2. Dynamic Theme Switching

Frontend: Use a form to submit theme changes:

<form action="{{ path('liip_theme_switch') }}" method="post">
    <select name="theme">
        {% for theme in themes %}
            <option value="{{ theme }}">{{ theme|humanize }}</option>
        {% endfor %}
    </select>
    <button type="submit">Switch</button>
</form>

Backend: Set theme via service:

$this->get('liip_theme')->setTheme('dark');

3. Theme-Specific Assets

Override assets (CSS/JS) per theme:

src/YourBundle/Resources/public/themes/
├── default/
│   └── styles.css
└── dark/
    └── styles.css

Reference in Twig:

<link rel="stylesheet" href="{{ asset('bundles/yourbundle/themes/' ~ activeTheme ~ '/styles.css') }}">

4. Integration with Twig

Access active theme in templates:

{% set activeTheme = app.request.attributes.get('_liip_theme') %}
{% if activeTheme == 'dark' %}
    <body class="dark-theme">
{% endif %}

5. Fallback Logic

Use {% extends %} with fallback:

{% extends activeTheme ~ '/base.html.twig' if activeTheme != 'default' else 'base.html.twig' %}

Gotchas and Tips

Pitfalls

Routing Conflicts:
- Ensure /theme prefix doesn’t clash with existing routes. Use _liip_theme route name as a prefix:
```
liip_theme:
    resource: "@LiipThemeBundle/Resources/config/routing.xml"
    prefix: /_liip_theme
```
Caching Issues:
- Clear cache after adding new themes:
```
php bin/console cache:clear
```
Case Sensitivity:
- Theme names are case-sensitive. Use strtolower() when validating:
```
$theme = strtolower($request->get('theme'));
```
Missing Fallback:
- If a theme file is missing, the bundle silently falls back to Resources/views/. Add validation:
```
liip_theme:
    strict_theme_check: true  # Throws exception if theme not found
```

Debugging Tips

Check Active Theme: Dump the active theme in a template:
```
{{ dump(app.request.attributes.get('_liip_theme')) }}
```

Verify Theme Paths: Use Symfony’s asset() helper to debug paths:

{{ asset('bundles/yourbundle/themes/' ~ activeTheme ~ '/missing-file.css') }}

Logging: Enable debug mode to log theme switches:
```
liip_theme:
    debug: true
```

Extension Points

Custom Theme Storage: Override theme storage (e.g., database) by extending Liip\ThemeBundle\Storage\ThemeStorageInterface:

class DatabaseThemeStorage implements ThemeStorageInterface {
    public function getActiveTheme() { /* ... */ }
    public function setActiveTheme($theme) { /* ... */ }
}

services:
    liip_theme.storage:
        class: App\Service\DatabaseThemeStorage

Theme Events: Listen for theme changes via events:

$eventDispatcher->addListener(Liip\ThemeBundle\Event\ThemeEvent::THEME_CHANGED, function ($event) {
    // Log or trigger actions on theme switch
});

Dynamic Theme Loading: Load themes from external sources (e.g., S3) by implementing Liip\ThemeBundle\Loader\ThemeLoaderInterface.

Performance

Preload Themes: Cache theme metadata at bootstrap:

$this->get('liip_theme')->preloadThemes(['default', 'dark']);

Asset Versioning: Append theme name to asset URLs to bypass cache:

<link rel="stylesheet" href="{{ asset('bundles/yourbundle/themes/' ~ activeTheme ~ '/styles.css?v=' ~ activeTheme) }}">

Theme Bundle Laravel Package