Core Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-thememanager/core
   

   Ensure Contao CMS is installed (v4.13+ recommended) and the package is enabled in config/autoload.php:

   'contrib' => [
       'thememanager' => true,
   ],
   

2. First Use Case: Basic Theme Activation

   • Navigate to Contao Backend → System → Theme Manager.
   • Upload a theme folder (e.g., my-theme) via the UI or manually to themes/.
   • Activate the theme in Settings → Themes (select my-theme as default).

3. CLI Quick Check Verify installation with:

   php vendor/bin/contao-console thememanager:list
   

   Outputs active/inactive themes.

Implementation Patterns

1. Theme Lifecycle Management

• Activation/Deactivation Use the ThemeManager service to toggle themes programmatically:

  $themeManager = \Contao\CoreBundle\Framework::getContainer()->get('thememanager.manager');
  $themeManager->activateTheme('my-theme'); // Replace with your theme name
  

• Theme Dependencies Define dependencies in theme.xml (e.g., requires="bootstrap5"). The manager auto-blocks activation if dependencies are missing.

2. Dynamic Theme Switching

• User-Specific Themes Override the default theme per user via a hook:

  // config/config.php
  $GLOBALS['TL_HOOKS']['loadDataContainer'][] = function() {
      if (\Input::get('do') === 'themes') {
          $user = \BackendUser::getInstance();
          if ($user->theme !== '') {
              \System::loadLanguageFile('tl_theme');
              \Database::getInstance()->prepare("UPDATE tl_theme SET default=? WHERE name=?")
                  ->execute($user->theme, $user->theme);
          }
      }
  };
  

• Frontend Theme Detection Use the ThemeManager to fetch the active theme in templates:

  {{ app.container.get('thememanager.manager').getActiveTheme().getName() }}
  

3. Custom Theme Fields

Extend theme metadata via theme.xml:

<theme name="my-theme" description="My Custom Theme">
    <meta>
        <author>Your Name</author>
        <version>1.0.0</version>
        <contributors>
            <contributor>Contributor 1</contributor>
        </contributors>
    </meta>
    <config>
        <option name="dark_mode" type="boolean" default="false" label="Enable Dark Mode"/>
    </config>
</theme>

Access config in PHP:

$theme = $themeManager->getTheme('my-theme');
$darkMode = $theme->getConfig('dark_mode', false);

4. Integration with Contao Modules

• Theme-Aware Modules Dynamically load CSS/JS based on the active theme:

  $theme = $themeManager->getActiveTheme();
  if ($theme->getName() === 'my-theme') {
      $this->addCssFile('bundles/mytheme/css/style.css');
  }
  

• Fallback Themes Set a fallback theme in config/config.php:

  $GLOBALS['TL_THEMES'] = [
      'fallback' => 'default-theme',
  ];
  

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear Contao cache after theme updates:

     php vendor/bin/contao-console cache:clear
     

   • Use thememanager:clear-cache for theme-specific cache:

     php vendor/bin/contao-console thememanager:clear-cache
     

2. Theme Naming Conflicts

   • Avoid hyphens (-) in theme names; use underscores (_) instead.
   • Validate names via:

     if (!$themeManager->isValidThemeName('my-theme')) {
         throw new \RuntimeException('Invalid theme name');
     }
     

3. Dependency Hell

   • Test dependencies locally before deploying. Use:

     php vendor/bin/contao-console thememanager:validate
     

Debugging Tips

• Log Theme Events Enable debug mode in config/local.php:

  'debug' => true,
  

  Check logs for ThemeManager events in var/log/contao.log.

• Inspect Active Theme Dump the active theme object:

  \Contao\CoreBundle\Framework::getContainer()->get('debug.dump')->dump($themeManager->getActiveTheme());
  

Extension Points

1. Custom Theme Validators Extend validation logic by implementing ThemeManagerValidatorInterface:

   class CustomThemeValidator implements ThemeManagerValidatorInterface {
       public function validate(Theme $theme): bool {
           return $theme->getConfig('dark_mode') !== true;
       }
   }
   

   Register in config/config.php:

   $GLOBALS['TL_THEME_VALIDATORS'][] = CustomThemeValidator::class;
   

2. Post-Activation Hooks Trigger actions after theme activation:

   $GLOBALS['TL_HOOKS']['afterThemeActivation'][] = function($themeName) {
       \System::log("Theme '$themeName' activated!", __FILE__, TL_ERROR);
   };
   

3. Theme Preview in Backend Override the preview template by copying:

   vendor/contao-thememanager/core/src/Resources/contao/themes/preview.tpl
   

   to templates/.

Performance Quirks

• Lazy-Loading Themes Themes are loaded on-demand. For large sites, preload critical themes:

  $themeManager->preloadTheme('my-theme');
  

• Asset Optimization Use thememanager:build to concatenate/minify theme assets:

  php vendor/bin/contao-console thememanager:build --theme=my-theme