Contao Theme Manager Bridge Laravel Package

Getting Started

Minimal Setup

1. Install the Package Add the package via Composer in your Laravel/Contao project:

   composer require oveleon/contao-theme-manager-bridge
   

   Ensure your project uses Contao 4.11+ (or a compatible version) and Symfony 5.4+ (if leveraging Symfony components).

2. Register the Service Provider In config/app.php, add the bridge provider to the providers array:

   Oveleon\ThemeManagerBridge\ThemeManagerBridgeServiceProvider::class,
   

3. Publish Configuration (Optional) Publish the default config to customize behavior:

   php artisan vendor:publish --provider="Oveleon\ThemeManagerBridge\ThemeManagerBridgeServiceProvider" --tag="config"
   

   This generates config/theme-manager-bridge.php.

4. First Use Case: Theme Activation Use the bridge to activate a theme via Contao’s CLI or a custom command:

   php contao:theme:activate my-theme-package
   

   Or programmatically:

   use Oveleon\ThemeManagerBridge\Facades\ThemeManagerBridge;
   
   ThemeManagerBridge::activateTheme('my-theme-package');
   

Implementation Patterns

Workflow: Theme Development with Composer

1. Structure Your Themes Organize themes as Composer packages in vendor/ or a themes/ directory (e.g., themes/my-theme/). Each theme should:

   • Include a composer.json with a type: contao-theme.
   • Define assets (CSS/JS) in a Resources/ directory (e.g., Resources/public/).

2. Autoload Theme Assets Use the bridge to auto-register theme assets in Laravel’s asset pipeline:

   // In a service provider or bootstrap file
   $bridge = app(Oveleon\ThemeManagerBridge\ThemeManagerBridge::class);
   $bridge->registerThemeAssets('my-theme-package', [
       'css' => ['Resources/public/css/style.css'],
       'js'  => ['Resources/public/js/script.js'],
   ]);
   

3. Dynamic Theme Switching Integrate with Laravel’s routing or middleware to switch themes:

   // Example: Middleware to set theme based on request
   public function handle($request, Closure $next) {
       $theme = ThemeManagerBridge::getActiveTheme();
       app()->bind('theme', fn() => $theme);
       return $next($request);
   }
   

4. Hook into Contao Events Extend Contao’s theme lifecycle with Laravel events:

   // Listen for theme activation/deactivation
   event(new ThemeActivated($themeName));
   

   Register listeners in EventServiceProvider:

   protected $listen = [
       \Oveleon\ThemeManagerBridge\Events\ThemeActivated::class => [
          \App\Listeners\LogThemeActivation::class,
      ],
   ];
   

5. Deployment Automation Use Laravel’s artisan commands to sync themes during deployment:

   php artisan theme-manager-bridge:sync
   

   This updates symlinks, clears caches, and ensures assets are published.

Gotchas and Tips

Pitfalls

1. Namespace Collisions

   • The bridge assumes themes are Composer packages. Avoid naming conflicts by prefixing theme namespaces (e.g., Vendor\ThemeName\).
   • Fix: Use config/theme-manager-bridge.php to remap namespaces:

     'theme_namespace_prefix' => 'App\\Themes\\',
     

2. Asset Pipeline Conflicts

   • If themes use Laravel Mix/Webpack, ensure mix-manifest.json is merged correctly. The bridge does not auto-discover Mix assets.
   • Fix: Manually register Mix assets in resources/js/bootstrap.js:

     window.themeAssets = {
         'my-theme': require('../themes/my-theme/mix-manifest.json'),
     };
     

3. Caching Issues

   • Contao’s theme cache may not update immediately after activation. Clear caches explicitly:

     php contao:clear-cache
     php artisan cache:clear
     

   • Tip: Use the bridge’s invalidateCache() method:

     ThemeManagerBridge::invalidateCache('my-theme-package');
     

4. Symfony Dependency Conflicts

   • If your project uses Symfony components (e.g., symfony/console), ensure versions align with Contao’s requirements (check contao/core-bundle).
   • Tip: Pin versions in composer.json:

     "require": {
         "symfony/console": "5.4.*",
         "contao/core-bundle": "^4.11"
     }
     

5. Theme Updates

   • The bridge does not auto-update themes via Composer. Use a post-update script:

     composer require oveleon/my-theme:^2.0 --update-with-dependencies
     php artisan theme-manager-bridge:sync
     

Debugging Tips

1. Enable Debug Mode Set debug: true in config/theme-manager-bridge.php to log theme operations:

   'debug' => env('APP_DEBUG', false),
   

2. Check Theme Registration Verify themes are registered via:

   dd(ThemeManagerBridge::getRegisteredThemes());
   

3. Symlink Issues If assets fail to load, check symlinks in public/:

   ls -la public/themes/
   

   Rebuild symlinks with:

   php artisan theme-manager-bridge:sync --force
   

Extension Points

1. Custom Theme Loaders Extend the bridge’s theme loader by implementing Oveleon\ThemeManagerBridge\Contracts\ThemeLoaderInterface:

   class CustomThemeLoader implements ThemeLoaderInterface {
       public function load(string $themeName): array {
           return ['path' => "/custom/path/to/{$themeName}"];
       }
   }
   

   Bind it in a service provider:

   $this->app->bind(ThemeLoaderInterface::class, CustomThemeLoader::class);
   

2. Theme Previews Integrate with Laravel’s view system to render theme previews:

   // In a controller
   return view('themes.preview', [
       'theme' => ThemeManagerBridge::getThemePreview('my-theme-package'),
   ]);
   

3. API Integration Expose theme status via Laravel’s API:

   Route::get('/api/themes', function () {
       return ThemeManagerBridge::getActiveTheme();
   });
   

   Protect routes with middleware (e.g., auth:api).

4. Testing Mock the bridge in PHPUnit tests:

   $this->app->instance(ThemeManagerBridge::class, Mockery::mock(ThemeManagerBridge::class));
   

   Use ThemeManagerBridge::shouldReceive('activateTheme')->once() for assertions.