Getting Started

Minimal Setup

Installation
```
composer require apie/twig-template-layout-renderer
```
Requires Twig (install via composer require twig/twig).

Basic Registration In your Laravel service provider (e.g., AppServiceProvider):

use Apie\TwigTemplateLayoutRenderer\TwigLayoutRenderer;

public function register()
{
    $this->app->singleton(TwigLayoutRenderer::class, function ($app) {
        return new TwigLayoutRenderer($app['twig']);
    });
}

First Use Case Render a Twig template with a layout:

$renderer = app(TwigLayoutRenderer::class);
$content = $renderer->render('partials/content.twig', [
    'title' => 'Hello World'
]);
$layout = $renderer->render('layouts/main.twig', [
    'block_content' => $content
]);

Implementation Patterns

Core Workflow

Template Segmentation Use layouts (layouts/main.twig) to wrap reusable structures (headers, footers, navigation) and partials (partials/*.twig) for modular content.

{# layouts/main.twig #}
<!DOCTYPE html>
<html>
    <head>
        <title>{% block title %}{% endblock %}</title>
    </head>
    <body>
        {% block content %}{% endblock %}
    </body>
</html>

Dynamic Block Injection Pass rendered partials as block variables:

$content = $renderer->render('partials/dashboard.twig', ['stats' => $statsData]);
$layout = $renderer->render('layouts/dashboard.twig', [
    'block_content' => $content,
    'block_sidebar' => $renderer->render('partials/sidebar.twig')
]);

Integration with Laravel Views Extend Laravel’s view system by creating a custom View facade:

// app/Providers/AppServiceProvider.php
View::macro('renderLayout', function ($layout, $data = []) {
    return app(TwigLayoutRenderer::class)->render($layout, $data);
});

Usage:

return View::renderLayout('layouts/app.twig', [
    'block_header' => $renderer->render('partials/header.twig')
]);

API Response Rendering Combine with Laravel’s Response for API-driven templates:

return response($renderer->render('emails/welcome.twig', $data))
    ->header('Content-Type', 'text/html');

Advanced Patterns

Template Inheritance Leverage Twig’s native extends and blocks for nested layouts:

{# child.twig #}
{% extends 'layouts/base.twig' %}
{% block body %}
    <h1>{{ title }}</h1>
    {{ parent() }} {# Inherit parent block content #}
{% endblock %}

Dynamic Layout Selection Use a factory pattern to switch layouts based on context:

$layoutRenderer = new TwigLayoutRenderer($twig);
$layout = $layoutRenderer->render(
    $user->preferredLayout ?: 'layouts/default.twig',
    $data
);

Caching Rendered Layouts Cache rendered layouts for performance:

$cacheKey = 'layout_' . md5(serialize($data));
$layout = Cache::remember($cacheKey, now()->addHours(1), function () use ($renderer, $data) {
    return $renderer->render('layouts/main.twig', $data);
});

Error Handling Wrap rendering in try-catch blocks to handle template errors gracefully:

try {
    $layout = $renderer->render('layouts/error.twig', ['error' => $e]);
} catch (\Twig\Error\LoaderError $e) {
    return response('Template not found', 500);
}

Gotchas and Tips

Common Pitfalls

Block Name Collisions Ensure block names in partials match those in layouts exactly (case-sensitive). Example:

{# Layout #}
{% block content %}{% endblock %}
{# Partial #}
{% block content %} <!-- Must match -->
    {{ partialContent }}
{% endblock %}

Circular Dependencies Avoid layouts that extend other layouts recursively (e.g., A.twig extends B.twig, which extends A.twig). Twig will throw a LoaderError.
Missing extends in Partials Partials should not use extends; they are meant to be injected into layouts. Doing so will cause Twig to ignore the layout’s blocks.
Twig Environment Configuration Ensure your Twig environment is properly configured (e.g., paths, debug mode) before using the renderer:
```
$twig = new \Twig\Environment($loader, [
    'cache' => storage_path('framework/views'),
    'debug' => config('app.debug'),
]);
```

Debugging Tips

Enable Twig Debug Mode Set 'debug' => true in your Twig environment to get detailed error messages and template line numbers.

Check Template Paths Verify paths in your Twig\Loader\FilesystemLoader are correct. Use absolute paths if needed:

$loader = new \Twig\Loader\FilesystemLoader([
    resource_path('views'),
    base_path('vendor/apie/layouts') // Example: Custom vendor layouts
]);

Inspect Rendered Output Use var_dump() or dd() to debug block variables:

$data = [
    'block_content' => $renderer->render('partials/debug.twig', ['var' => $var])
];

Log Template Errors Catch and log Twig errors to track issues:

try {
    $renderer->render('layouts/main.twig', $data);
} catch (\Twig\Error\Error $e) {
    \Log::error('Twig Error: ' . $e->getMessage() . ' in ' . $e->getTemplateLine());
}

Extension Points

Custom Block Strategies Extend the renderer to support custom block logic (e.g., merging blocks with defaults):

class CustomTwigLayoutRenderer extends TwigLayoutRenderer {
    protected function mergeBlocks(array $blocks, array $data): array
    {
        // Custom logic here
        return parent::mergeBlocks($blocks, $data);
    }
}

Pre/Post-Render Hooks Add hooks to modify data before rendering or process output afterward:

$renderer->addPreRenderHook(function ($template, $data) {
    $data['global_var'] = 'value'; // Inject global data
    return $data;
});

Integration with Laravel Mix Use Laravel Mix to compile Twig templates into static assets for production:
```
// mix.js
mix.copy('resources/views', 'public/views');
```
Then configure Twig to load from public/views in production.
Support for Alternative Template Engines While this package is Twig-specific, you could abstract the renderer to support other engines (e.g., Blade) by implementing a common interface:
```
interface TemplateRendererInterface {
    public function render(string $template, array $data);
}
```

Twig Template Layout Renderer Laravel Package