Theme Bundle Laravel Package

Product Decisions This Supports

• Dynamic theming for Symfony applications: Enables A/B testing, user preference-based theming, or seasonal design changes without redeploying code.
• Modular architecture: Supports theming at the bundle level, allowing teams to own and customize themes independently (e.g., marketing vs. admin dashboards).
• Roadmap for design systems: Accelerates adoption of a design system by isolating theme variations (e.g., dark/light modes, brand-specific templates) per bundle.
• Build vs. buy: Avoids reinventing theming logic for Symfony apps, reducing dev time and technical debt. Justification for adoption hinges on Symfony’s dominance in enterprise/Laravel-adjacent stacks.
• Use cases:
  • Multi-brand portals (e.g., SaaS with white-labeling).
  • Localized designs (e.g., regional UI tweaks without full i18n overhauls).
  • Legacy migration (gradually theming old bundles while new ones use modern templates).

When to Consider This Package

• Avoid if:
  • Your app uses Twig 2.x (this bundle targets Twig 3+).
  • You need runtime theme switching (e.g., per-user sessions) without manual configuration—this requires app-level logic to set the active theme.
  • Your team prefers static site generators (e.g., Symfony + Vite) where theming is handled via build tools.
  • You’re using Laravel’s Blade (this is Symfony-specific; consider Laravel Mix or custom middleware for theming).
  • Maintenance risk: Last release in 2021; evaluate if the forked LiipThemeBundle (originally active) meets your needs or if a maintained alternative exists (e.g., Symfony’s Flex recipes).
• Look elsewhere if:
  • You need CSS/asset theming (e.g., swapping color schemes)—pair with tools like PostCSS variables or Sass mixins.
  • Your theming requires database-driven templates (this is file-system based; consider a CMS like Sylius or custom entity-based routing).

How to Pitch It (Stakeholders)

For Executives: "This package lets us ship multiple design variations (e.g., for different customer segments or regions) without rewriting templates. For example, we could A/B test a new dashboard theme for 10% of users without deploying new code—just by toggling a config flag. It’s a low-risk way to future-proof our UI for multi-brand or localized needs, and it aligns with our Symfony stack. The tradeoff? Minimal maintenance overhead since it’s a lightweight fork of a proven bundle."

For Engineering: *"LiipThemeBundle gives us bundle-level theming: each Symfony bundle (e.g., AcmeBlogBundle) can have its own theme directory (Resources/themes/dark/), falling back to default views if a file is missing. This is useful for:

• Isolating changes: Marketing can tweak the AcmeBlogBundle theme without touching core templates.
• Performance: Only load theme-specific assets (CSS/JS) when needed.
• Legacy support: Gradually theme old bundles while new ones use modern templates. Downsides: Requires Twig 3+, and theme switching needs app-level logic (e.g., via user preferences or route parameters). If we go this route, we’ll need to document the theming workflow for devs and QA."*

For Developers: *"This is a drop-in replacement for manual template overrides. To use it:

1. Install via Composer (liip/theme-bundle).
2. Enable the bundle in AppKernel.php.
3. Configure allowed themes in config/packages/liip_theme.yaml (e.g., themes: [default, dark, corporate]).
4. Set the active theme via a service or route parameter. Pro tip: Use {% extends 'theme::base.html.twig' %} in your templates to inherit from themed layouts. For dynamic themes (e.g., per-user), bind the active theme to a Twig global or use a listener on kernel.request."*