Getting Started

Minimal Setup

Install Dependencies:
```
composer require alphalemon/theme-engine-bundle
```
(Note: Due to legacy Symfony 2.3 requirements, ensure compatibility with your project or use a standalone installation as per the README.)

Register the Bundle: Add to app/AppKernel.php:

new AlphaLemon\ThemeEngineBundle\AlphaLemonThemeEngineBundle(),

Configure Propel ORM: Follow PropelBundle docs to set up Propel, then run:

app/console propel:database:create
app/console propel:build
app/console propel:insert-sql --for

Enable Routing: Add to app/config/routing.yml:

_alphaLemonThemeEngineBundle:
    resource: "@AlphaLemonThemeEngineBundle/Resources/config/routing.yml"

Install Assets:
```
app/console assets:install web
```
First Use Case: Create a theme bundle (e.g., AcmeDemoThemeBundle) with a Resources/views/ structure. Use slots in Twig:
```
{{ renderSlot('header') }}
```
Define slot content via the admin interface (accessible at /admin/themes).

Implementation Patterns

1. Theme Development Workflow

Structure a Theme Bundle:

AcmeDemoThemeBundle/
├── Resources/
│   ├── public/          # CSS/JS assets
│   ├── views/           # Twig templates (e.g., `base.html.twig`)
│   └── config/          # Theme-specific configs
└── AcmeDemoThemeBundle.php

Extend Symfony\Component\HttpKernel\Bundle\Bundle.

Slot-Based Templating:
- Define Slots: Use {{ renderSlot('slot_name') }} in templates.
- Populate Slots: Via the admin panel or programmatically:
```
$this->get('alpha_lemon.theme_engine.slot_manager')->setSlotContent('logo', '<img src="logo.png" />');
```
Theme Switching:
- Use the admin interface (/admin/themes) to enable/disable themes.
- Programmatically:
```
$this->get('alpha_lemon.theme_engine.theme_manager')->setActiveTheme('AcmeDemoThemeBundle');
```

2. Integration with Existing Code

Extend Base Templates: Override base.html.twig in your theme bundle to wrap content:

<!DOCTYPE html>
<html>
<head>
    {{ parent() }}  {# Inherits from parent theme/base template #}
    {{ renderSlot('head') }}
</head>
<body>
    {{ renderSlot('content') }}
</body>
</html>

Dynamic Slot Content: Fetch slot content in controllers:

$logoContent = $this->get('alpha_lemon.theme_engine.slot_manager')->getSlotContent('logo');
return $this->render('AcmeDemoThemeBundle:Default:index.html.twig', ['logo' => $logoContent]);

Asset Management: Use {% stylesheets %}/{% javascripts %} in Twig with theme-specific paths:

{% stylesheets 'bundles/acmedemotheme/css/*' filter='cssrewrite' %}
    <link rel="stylesheet" href="{{ asset_url }}">
{% endstylesheets %}

3. Autoloading Themes

Enable automatic theme bundle loading in AppKernel.php:

use AlphaLemon\ThemeEngineBundle\Core\Autoloader\ThemesAutoloader;

public function registerBundles() {
    $bundles = [
        // ... existing bundles
    ];
    $themes = new ThemesAutoloader();
    return array_merge($bundles, $themes->getBundles('path/to/themes/directory'));
}

Gotchas and Tips

Pitfalls

Propel Dependency:
- The bundle requires Propel ORM (not Doctrine). If using Doctrine, migrate or create a separate Propel schema for theme management.
- Fix: Use a lightweight Propel setup or fork the bundle to support Doctrine.
Slot Caching:
- Slots are cached aggressively. Clear cache after dynamic updates:
```
app/console cache:clear
app/console alpha_lemon:theme_engine:clear-slots
```
Theme Inheritance:
- Child themes must extend parent templates explicitly (e.g., {% extends 'parent_theme::base.html.twig' %}).
- Fix: Use {% block slot_name %}{{ parent() }}{% endblock %} for slot overrides.
Routing Conflicts:
- The bundle adds admin routes (/admin/themes). Ensure no conflicts with existing routes.
- Fix: Customize routing in routing.yml or use route prefixes.
Asset Paths:
- Hardcoded asset paths (e.g., /bundles/acmedemotheme/) break if the theme is renamed.
- Fix: Use Twig’s asset() with bundle-aware paths:
```
{{ asset('bundles/acmedemotheme/css/style.css') }}
```

Debugging Tips

Slot Not Rendering?: Check if the slot is registered in the database (alpha_lemon_theme_engine_slot table). Use:
```
app/console doctrine:query "SELECT * FROM alpha_lemon_theme_engine_slot"
```
Theme Not Loading: Verify the bundle is enabled in AppKernel and the theme directory is correct for autoloading.

Twig Errors: Enable Twig debug mode in config.yml:

twig:
    debug: true
    strict_variables: true

Extension Points

Custom Slot Types: Extend AlphaLemon\ThemeEngineBundle\Model\Slot to add metadata (e.g., max_length, allowed_html).
Theme Validation: Override AlphaLemon\ThemeEngineBundle\Validator\ThemeValidator to enforce custom theme structures.

Event Listeners: Subscribe to theme.switch or slot.update events:

// services.yml
alpha_lemon.theme_engine.listener.my_listener:
    class: Acme\Listener\ThemeListener
    tags:
        - { name: kernel.event_listener, event: alpha_lemon.theme_engine.theme.switch, method: onThemeSwitch }

API for Slot Management: Create a custom service to wrap SlotManager for business logic:

class CustomSlotService {
    private $slotManager;

    public function __construct(SlotManager $slotManager) {
        $this->slotManager = $slotManager;
    }

    public function updateHeaderSlot($content) {
        $this->slotManager->setSlotContent('header', $content, 'AcmeDemoThemeBundle');
    }
}

Theme Engine Bundle Laravel Package