Getting Started

Minimal Setup

Installation Add the package via Composer:
```
composer require spiral/twig-bridge
```
Register the TwigBridge service provider in config/app.php under providers:
```
Spiral\TwigBridge\TwigBridgeServiceProvider::class,
```

Basic Configuration Publish the default config (optional):

php artisan vendor:publish --provider="Spiral\TwigBridge\TwigBridgeServiceProvider" --tag="config"

Configure paths in config/twig-bridge.php:

'paths' => [
    'templates' => resource_path('views'),
    'cache'     => storage_path('framework/views'),
],

First Use Case: Rendering a Template Inject the TwigBridge into a controller or service:

use Spiral\TwigBridge\TwigBridgeInterface;

class HomeController
{
    public function __construct(private TwigBridgeInterface $twig)
    {
    }

    public function index()
    {
        return $this->twig->render('home.index.twig', [
            'title' => 'Welcome',
        ]);
    }
}

Implementation Patterns

Common Workflows

Template Rendering
- Basic Rendering: Use render() to output templates directly:
```
$html = $this->twig->render('email.welcome.twig', ['user' => $user]);
```
- Streaming: For large templates, use renderStream() to avoid memory issues:
```
$this->twig->renderStream('report.large.twig', $data);
```

Reusable Components

Embedding: Include partials or components:

{% embed 'layouts/base.twig' %}
    {{ block('content') }}
{% endembed %}

Macros: Define reusable snippets in Twig:

{% macro alert(type, message) %}
    <div class="alert alert-{{ type }}">{{ message }}</div>
{% endmacro %}

Integration with Laravel

Blade Compatibility: Use Twig alongside Blade by configuring paths:

'paths' => [
    'templates' => [resource_path('views/twig'), resource_path('views/blade')],
],

Middleware: Pass Twig environment to middleware for dynamic templates:

public function handle($request, Closure $next)
{
    $request->twig = $this->twig;
    return $next($request);
}

Dynamic Template Selection

Use runtime logic to select templates:

$template = $user->prefersDarkMode() ? 'dark.layout.twig' : 'light.layout.twig';
return $this->twig->render($template, $data);

Testing

Mock TwigBridgeInterface in tests:

$this->mock(TwigBridgeInterface::class)->shouldReceive('render')->once()->andReturn('<html>...</html>');

Integration Tips

Caching

Enable Twig cache for production:

'cache' => [
    'enabled' => env('APP_ENV') === 'production',
],

Clear cache manually:
```
php artisan twig:clear-cache
```

Extensions

$this->twig->getEnvironment()->addExtension(new \Your\CustomExtension());

Error Handling
- Configure Twig error handling in config/twig-bridge.php:
```
'debug' => env('APP_DEBUG', false),
```
Asset Management
- Use Twig’s asset() function (if integrated with Laravel Mix/Vite):
```
<link rel="stylesheet" href="{{ asset('css/app.css') }}">
```

Gotchas and Tips

Pitfalls

Path Configuration
- Ensure templates and cache paths are writable:
```
chmod -R 775 storage/framework/views
```
- Gotcha: Forgetting to publish config may lead to default paths not matching your project structure.
Namespace Conflicts
- Twig templates use twig namespace by default. Avoid naming conflicts with Laravel’s Blade directives:
```
{# Not @if, but {% if %} #}
```
Caching Quirks
- Gotcha: Disabling cache in development may slow down template rendering significantly.
- Clear cache after template changes:
```
php artisan twig:clear-cache
```
Dependency Injection
- Gotcha: Forgetting to inject TwigBridgeInterface will throw BindingResolutionException.
- Prefer constructor injection over service locator:
```
// Avoid:
$this->twig = app(TwigBridgeInterface::class);
```
Twig vs. Blade Syntax
- Gotcha: Mixing Twig and Blade syntax in the same template can cause parsing errors.
- Example of conflicting syntax:
```
{# Twig: {% if %} #}
@if(true) {# Blade: @if #}
    {{-- This will fail --}}
@endif
```

Debugging Tips

Enable Debug Mode Set debug: true in config/twig-bridge.php to get detailed error messages.
Template Not Found
- Verify the template path is correct (case-sensitive on Linux).
- Check paths.templates in config and ensure the file exists.
Variable Errors
- Twig is strict about undefined variables. Use {{ variable|default('fallback') }} to avoid errors.
Performance Issues
- Profile Twig rendering with twig:profile command (if available).
- Optimize templates by avoiding deep nesting and excessive filters.
Extension Conflicts
- Disable extensions one by one to isolate conflicts:
```
$env->removeExtension($extension);
```

Extension Points

Custom Filters Add a filter to Twig:

$this->twig->getEnvironment()->addFilter(new \Twig\TwigFilter('custom_filter', function ($value) {
    return strtoupper($value);
}));

Global Variables Pass data to all templates:

$this->twig->getEnvironment()->addGlobal('app_name', config('app.name'));

Custom Functions Register a Twig function:

$this->twig->getEnvironment()->addFunction(new \Twig\TwigFunction('greet', function ($name) {
    return "Hello, $name!";
}));

Event Listeners Listen to Twig events (e.g., Twig\SourceContextLoadedEvent):

$this->twig->getEnvironment()->addEventListener(\Twig\SourceContextLoadedEvent::class, function ($event) {
    // Log template paths
});

Override Default Environment For advanced use cases, bind a custom Twig\Environment:

$this->app->bind(TwigBridgeInterface::class, function ($app) {
    $loader = new \Twig\Loader\FilesystemLoader($app['config']['twig-bridge.paths.templates']);
    $env = new \Twig\Environment($loader, [
        'cache' => $app['config']['twig-bridge.paths.cache'],
    ]);
    return new TwigBridge($env);
});

Twig Bridge Laravel Package