Getting Started

Minimal Setup

Install the Bundle Add to composer.json:

composer require oveleon/contao-theme-compiler-bundle

Enable in config/bundles.php:

return [
    // ...
    Oveleon\ContaoThemeCompilerBundle\OveleonContaoThemeCompilerBundle::class => ['all' => true],
];

Configure the Bundle Publish the default config:
```
php bin/console oveleon:theme-compiler:install
```
Edit config/packages/oveleon_theme_compiler.yaml to define:
- Source directories (e.g., src/Resources/public/css, src/Resources/public/js).
- Output paths (e.g., web/assets/).
- Build tools (e.g., postcss, webpack, or vite).
First Compilation Run the compiler:
```
php bin/console oveleon:theme-compiler:compile
```
Verify assets appear in web/assets/ (or your configured output).

First Use Case: Local Development Workflow

Watch Mode: Start a watcher for live updates:

php bin/console oveleon:theme-compiler:watch

Theme-Specific Compilation: Override config per theme by creating config/packages/oveleon_theme_compiler_[theme_name].yaml.
Contao Integration: Use the generated assets in Contao templates via:
```
<link rel="stylesheet" href="{{ asset('assets/css/main.css') }}">
```

Implementation Patterns

Workflow Integration

Git Hooks for Automation Add a post-merge hook to compile assets on branch updates:
```
php bin/console oveleon:theme-compiler:compile --env=dev
```
Use --env to target specific environments (e.g., prod for minified builds).
Modular Theme Development
- Theme Isolation: Store theme-specific assets in themes/[theme_name]/assets/.
- Shared Config: Extend base config in config/packages/oveleon_theme_compiler_[theme_name].yaml:
```
oveleon_theme_compiler:
    themes:
        my_theme:
            source: "%kernel.project_dir%/themes/my_theme/assets"
            output: "web/assets/my_theme"
```
- Inheritance: Use @import in CSS/SCSS to share base styles across themes.

Build Pipeline

Multi-Tool Support: Configure tools per file type:

tools:
    css:
        postcss: true
        options:
            plugins: [autoprefixer, cssnano]
    js:
        vite: true

Environment-Specific Builds: Use Symfony’s %kernel.environment% to toggle features:
```
tools:
    js:
        sourcemaps: "%kernel.debug%"
```

Contao Asset Management
- Dynamic Asset URLs: Use Contao’s Url::asset() helper with compiled paths:
```
Url::asset('assets/css/main.css', true); // Force fresh load
```
- Cache Busting: Leverage Contao’s Asset::addCss() with versioned filenames:
```
Asset::addCss('assets/css/main-' . filemtime('web/assets/css/main.css') . '.css');
```

Integration Tips

Laravel Mix/Vite: Bridge gaps by configuring the bundle to use Laravel’s build tools:

tools:
    js:
        vite: true
        config: "vite.config.js" # Path to your Vite config

Contao Backend Assets: Compile backend-specific assets separately:

themes:
    backend:
        source: "%kernel.project_dir%/src/Resources/contao/backend"
        output: "system/modules/backend/assets"

Database-Driven Themes: Sync compiled assets with theme selections via Contao’s tl_theme table:

// In a Contao hook (e.g., `onInitializeSystem`)
if ($this->Input->get('act') === 'switch_theme') {
    $theme = $this->Input->get('theme');
    $this->compileTheme($theme);
}

Gotchas and Tips

Pitfalls

Caching Issues
- Symptom: Changes to source files don’t reflect in compiled assets.
- Fix: Clear Contao’s cache and the bundle’s cache:
```
php bin/console cache:clear
php bin/console oveleon:theme-compiler:clear-cache
```
- Debug: Check var/cache/dev/oveleon_theme_compiler for stale manifests.
Tool Configuration Conflicts
- Symptom: Build fails with "Tool not found" errors.
- Fix: Ensure tools (e.g., postcss, webpack) are installed globally or via devDependencies:
```
npm install -g postcss-cli
```
- Fallback: Use the bundle’s default toolchain by omitting tools config.
File Overwrites
- Symptom: Compiled assets overwrite each other during theme switches.
- Fix: Use unique output paths per theme or append theme names to filenames:
```
output: "web/assets/%theme_name%"
```
Contao Asset Versioning
- Symptom: Browsers cache old asset versions.
- Fix: Enable Contao’s asset versioning in config/local.php:
```
$GLOBALS['TL_CONFIG']['versionAssets'] = true;
```

Debugging

Dry Runs Test changes without overwriting files:
```
php bin/console oveleon:theme-compiler:compile --dry-run
```
Outputs a diff of changes to var/log/oveleon_theme_compiler.log.

Verbose Logging Enable debug mode for detailed logs:

php bin/console oveleon:theme-compiler:compile --env=dev -v

Manifest Inspection Check the generated manifest file (e.g., web/assets/manifest.json) for:
- Missing source files.
- Incorrect hashes (indicating tool misconfiguration).

Extension Points

Custom Compilers Extend the bundle’s compiler system by implementing Oveleon\ContaoThemeCompilerBundle\Compiler\CompilerInterface:

namespace App\Compiler;

use Oveleon\ContaoThemeCompilerBundle\Compiler\CompilerInterface;

class CustomCompiler implements CompilerInterface {
    public function compile(string $source, string $output): void {
        // Custom logic (e.g., call a CLI tool)
    }
}

compilers:
    custom:
        class: App\Compiler\CustomCompiler
        extensions: ['.custom']

Pre/Post-Compile Hooks Use Symfony events to hook into the compilation process:

// In a service or controller
$dispatcher->addListener(
    OveleonThemeCompilerEvents::PRE_COMPILE,
    function (PreCompileEvent $event) {
        // Modify $event->getFiles() or $event->getOptions()
    }
);

Dynamic Theme Detection Override Oveleon\ContaoThemeCompilerBundle\Theme\ThemeDetectorInterface to auto-detect themes from Contao’s database or filesystem.

Configuration Quirks

Environment Variables Use Symfony’s %env() in config for dynamic paths:

output: "%kernel.project_dir%/%env(ASSET_OUTPUT_DIR)%/assets"

Set via .env:

ASSET_OUTPUT_DIR=web/custom_assets

Theme Inheritance Merge configs for child themes by extending parent configs:

# config/packages/oveleon_theme_compiler_child.yaml
extends: oveleon_theme_compiler_parent.yaml
oveleon_theme_compiler:
    tools:
        css:
            postcss:
                options:
                    plugins: [parent_plugins, child_plugin]

Excluding Files Skip specific files/folders in compilation:

exclude:
    - "src/Resources/public/css/_private.scss"
    - "node_modules/"

Contao Theme Compiler Bundle Laravel Package