Getting Started

Minimal Setup

Installation Add the package via Composer:

composer require sylius/twig-hooks

twig:
    extensions:
        - Sylius\Component\Twig\Hooks\TwigHooksExtension

First Hook Usage Define a hook in your Twig template:
```
{% hooks 'hook_name' %}
```
Register a hook in your controller or service:
```
$this->twigHooks->addHook('hook_name', 'template_path');
```

Basic Example In a controller:

public function showAction(Request $request)
{
    $this->twigHooks->addHook('product_page_header', 'product/_partials/header.html.twig');
    return $this->render('product/show.html.twig');
}

Where to Look First

Documentation: Sylius Stack Docs (search for "Twig Hooks").
Source Code: Focus on Sylius\Component\Twig\Hooks\TwigHooksExtension and HooksNode for core logic.
Sylius Ecosystem: Check how Sylius uses it in their themes (e.g., Sylius Theme).

Implementation Patterns

Common Workflows

Dynamic Layouts Use hooks to modularize templates without inheritance:
```
{% hooks 'sidebar' %}
{% hooks 'footer' %}
```

Conditional Hooks Register hooks conditionally in controllers:

if ($user->isAdmin()) {
    $this->twigHooks->addHook('admin_toolbar', 'admin/_toolbar.html.twig');
}

Hooks with Data Pass variables to hooks via addHookWithData:

$this->twigHooks->addHookWithData(
    'product_extra_info',
    'product/_partials/extra_info.html.twig',
    ['attributes' => $product->getAttributes()]
);

Global Hooks Register hooks globally in a service (e.g., event subscriber):

public function onKernelRequest(GetResponseEvent $event)
{
    $this->twigHooks->addHook('global_header', 'shared/_header.html.twig');
}

Integration Tips

Theme Development: Use hooks to override or extend Sylius themes without modifying core templates.
Plugin System: Build a plugin architecture where third-party bundles can inject hooks dynamically.
Caching: Hooks are rendered at runtime, so avoid heavy computations. Cache hook templates if possible:
```
{% cache 'hook_product_sidebar_' ~ product.id %}
    {% hooks 'product_sidebar' %}
{% endcache %}
```

Gotchas and Tips

Pitfalls

Hook Order Hooks are rendered in the order they are added. Use addHookFirst to prepend:
```
$this->twigHooks->addHookFirst('hook_name', 'template_path');
```
Missing Templates If a hook template is missing, Twig will throw an error. Handle gracefully:
```
{% hooks 'hook_name' ignore_missing %}
```
Circular Dependencies Avoid hooks that reference each other (e.g., hook_a includes hook_b, which includes hook_a).
Performance Each hook adds a Twig node compilation overhead. Benchmark heavily used hooks.

Debugging

Enable Twig Debugging Set TWIG_DEBUG=1 in your .env to see hook-related errors and template paths.
Check Hook Registration Use dump($this->twigHooks->getHooks()) to inspect registered hooks in a controller.

Extension Points

Custom Hook Nodes Extend HooksNode to add logic (e.g., validate hook names or modify rendering).
Hook Events Dispatch events when hooks are added/rendered (e.g., HookAddedEvent).
Hook Storage Override the default storage (e.g., use a database or Redis for distributed systems).

Config Quirks

Namespace Conflicts Ensure hook names are unique across bundles (e.g., prefix with your bundle name: mybundle_product_header).

Template Paths Use @BundleName/ or :: syntax for absolute paths:

{% hooks 'hook_name' with {'template': '@MyBundle/hook/template.html.twig'} %}

Pro Tips

Hook Documentation Document hooks in your bundle’s README with examples and expected data.

Hook Testing Test hooks in isolation using TwigHooks directly:

$twigHooks = new TwigHooks();
$twigHooks->addHook('test', 'test.html.twig');
$this->assertStringContainsString('Hook content', $twigHooks->renderHooks($twig, 'test'));

Sylius Integration Leverage Sylius’s ThemeContext to pass theme-specific hooks dynamically.

Twig Hooks Laravel Package