Getting Started

Minimal Setup

Installation
```
composer require ezsystems/ezplatform-design-engine
```
Ensure your project extends EzSystems\DesignEngineBundle\EzSystemsDesignEngineBundle in config/bundles.php.

Basic Configuration Add the bundle to config/packages/ezplatform_design_engine.yaml:

ezplatform_design_engine:
    design_engine:
        enabled: true
        default_design: "default"

First Use Case: Rendering a Page Inject the DesignEngine service and use it in a controller:

use EzSystems\DesignEngineBundle\Service\DesignEngine;

public function renderPage(DesignEngine $designEngine, string $contentId)
{
    $content = $this->contentService->loadContent($contentId);
    $renderedContent = $designEngine->renderContent($content);
    return new Response($renderedContent);
}

Key Files to Review
- config/packages/ezplatform_design_engine.yaml (core config)
- src/EzSystems/DesignEngineBundle/Resources/config/services.yaml (service definitions)
- src/EzSystems/DesignEngineBundle/Service/DesignEngine.php (main service class)

Implementation Patterns

Core Workflows

1. Dynamic Content Rendering

Use the DesignEngine service to render content with custom designs:

$designEngine->renderContent($content, 'custom_design_name');

Pattern: Pass a Content object and an optional design name. The engine resolves the design and renders the content accordingly.
Use Case: Override default rendering for specific content types or sections.

2. Design Registration

Extend or register new designs via YAML or PHP:

# config/packages/ezplatform_design_engine.yaml
ezplatform_design_engine:
    designs:
        custom_design:
            template: "@MyBundle/designs/custom.html.twig"
            content_types: ["article", "blog_post"]

Pattern: Define designs with templates and allowed content types. Use @Bundle/designs/ for template paths.
Use Case: Create reusable design templates for different content structures.

3. Twig Integration

Access the DesignEngine in Twig templates:

{{ render(content, 'design_name') }}

Pattern: Use the render Twig function (auto-registered) to render content with a specific design.
Use Case: Embed dynamic content in layouts or partials.

4. Event-Driven Extensions

Listen to DesignEngineEvents to modify rendering:

use EzSystems\DesignEngineBundle\Event\DesignEngineEvent;

// In a service:
public function onDesignRender(DesignEngineEvent $event)
{
    $event->getContent()->setField('custom_field', 'value');
}

Pattern: Subscribe to design.engine.render or design.engine.post_render events.
Use Case: Inject custom logic (e.g., A/B testing, analytics) during rendering.

5. Content Type-Specific Designs

Map designs to content types in config:

ezplatform_design_engine:
    designs:
        article_design:
            template: "@MyBundle/designs/article.html.twig"
            content_types: ["article"]

Pattern: Use content_types to restrict designs to specific content types.
Use Case: Ensure articles render differently from news items.

Integration Tips

With Symfony Controllers

use EzSystems\DesignEngineBundle\Service\DesignEngine;
use Symfony\Component\HttpFoundation\Response;

public function show(DesignEngine $designEngine, Content $content)
{
    $html = $designEngine->renderContent($content, 'mobile_design');
    return new Response($html);
}

With API Platform

Override serialization for dynamic rendering:

use EzSystems\DesignEngineBundle\Service\DesignEngine;
use ApiPlatform\Core\Serializer\SerializerContextBuilderInterface;

public function __serialize(DesignEngine $designEngine, SerializerContextBuilderInterface $contextBuilder)
{
    $context = $contextBuilder->createArrayContext([]);
    return [
        'html' => $designEngine->renderContent($this, 'api_design'),
        'data' => $this,
    ];
}

With Custom Content Types

Extend the Content class to add design-specific fields:

use EzSystems\DesignEngineBundle\Api\DesignAwareInterface;

class CustomContent implements DesignAwareInterface
{
    public function getDesign(): ?string
    {
        return $this->designField->value;
    }
}

Gotchas and Tips

Pitfalls

1. Design Resolution Order

The engine resolves designs in this order:
1. Explicitly passed design name.
2. Content’s design field (if DesignAwareInterface is implemented).
3. Default design (from config).
4. Falls back to a generic template.
Fix: Ensure your content types implement DesignAwareInterface if relying on field-based designs.

2. Template Paths

Twig templates must be in Resources/views/ or Resources/templates/.
Gotcha: Paths like @MyBundle/designs/custom.html.twig are resolved relative to the bundle’s Resources/ directory.
Fix: Use absolute paths (e.g., @MyBundle/designs/custom.html.twig) or configure custom template locations.

3. Caching Quirks

The engine caches rendered output by default. Clear the cache after design changes:
```
php bin/console cache:clear
```

Tip: Disable caching in dev:

ezplatform_design_engine:
    design_engine:
        cache_enabled: false

4. Content Type Mismatches

If a design is assigned to a content type that doesn’t exist, the engine silently falls back to the default design.
Debug Tip: Enable debug mode and check logs for DesignEngine warnings.

5. Event Priority

Events like design.engine.render fire before template rendering.
Tip: Use design.engine.post_render for post-processing (e.g., modifying HTML).

Debugging Tips

1. Log Design Resolution

Add a subscriber to log design resolution:

use EzSystems\DesignEngineBundle\Event\DesignEngineEvent;

public function onDesignResolve(DesignEngineEvent $event)
{
    $this->logger->debug(
        'Resolved design',
        ['content_id' => $event->getContent()->id, 'design' => $event->getDesign()]
    );
}

2. Check Template Existence

Verify templates exist at the expected paths:

php bin/console debug:container ezplatform_design_engine.templating.loader

Tip: Use {{ dump(_self) }} in Twig to inspect the template context.

3. Validate Content Types

Ensure content types are correctly registered:
```
php bin/console debug:content-types
```

Fix: Rebuild content type definitions if missing:

php bin/console ezplatform:content-type:rebuild

Extension Points

1. Custom Design Resolvers

Extend EzSystems\DesignEngineBundle\Resolver\DesignResolverInterface to add logic:

use EzSystems\DesignEngineBundle\Resolver\DesignResolverInterface;

class CustomDesignResolver implements DesignResolverInterface
{
    public function resolve(Content $content): ?string
    {
        return $content->getField('custom_design_field')->value;
    }
}

services:
    App\DesignResolver\CustomDesignResolver:
        tags:
            - { name: ezplatform_design_engine.design_resolver }

2. Dynamic Template Loading

Override the template loader for custom sources (e.g., database):

use EzSystems\DesignEngineBundle\Templating\Loader\DesignTemplateLoaderInterface;

class DatabaseTemplateLoader implements DesignTemplateLoaderInterface
{
    public function getSource(string $name): string
    {
        return $this->database->fetchTemplate($name);
    }
}

ezplatform_design_engine:
    design_engine:
        template_loader: App\DesignResolver\DatabaseTemplateLoader

3. Post-Render Modifiers

Use design.engine.post_render to modify HTML:

use EzSystems\DesignEngineBundle\Event\DesignEngineEvent;

public function onPostRender(DesignEngineEvent $event)
{
    $html = $event->getHtml();
    $event->setHtml(str_replace('old-text', 'new-text', $html));
}

4. Conditional Designs

Use a resolver to apply designs based on conditions (e.g., user roles):

public function resolve(Content $content): ?string
{
    if ($this->security->isGranted('ROLE_ADMIN')) {
        return 'admin_design';
    }
    return null;
}

Ezplatform Design Engine Laravel Package