Unified Template Rendering Made Simple For PHP

A modern, flexible PHP template rendering library that provides a unified interface for multiple template engines and output formats.

Features

• 🔄 Unified Interface: One consistent API for all template engines.
• 🚀 Multiple Engine Support: Works with Twig, PHP, Markdown and more.
• 📄 Multiple Output Formats: Generate HTML, PDF from any template.
• 🔌 Extensible Architecture: Easy to add new engines and formats.
• 🎨 Powerful Formatting System: Format data consistently across all templates.
• 🛡️ Secure by Design: Safe template rendering and file handling.
• 🪶 Lightweight Core: Only load what you need.
• ⚡ Framework Agnostic: Use with any PHP framework.

Why Derafu\Renderer?

Traditional template systems often lock you into a single engine or require different handling for each format. Derafu\Renderer solves this by providing:

• A single, clean API for all template engines.
• Seamless switching between output formats.
• Consistent data formatting across all templates.
• Framework-agnostic design.
• Easy integration with existing systems.

Installation

Install via Composer:

composer require derafu/renderer

Basic Usage

use Derafu\Renderer\Factory\RendererFactory;

// Create renderer with engines Twig and PDF.
$renderer = RendererFactory::create([
    'engines' => ['twig', 'pdf'],
    'paths' => ['/path/to/templates'],
]);

// Render templates in different engines.
$html = $renderer->render('template.html.twig', ['name' => 'John']);
$pdf = $renderer->render('template.html.twig', ['name' => 'John'], ['engine' => 'pdf']);

Template Engines

Twig Templates

// template.html.twig
<h1>Hello !</h1>
<p>Today is </p>

PHP Templates

// template.php
<h1>Hello <?= $name ?>!</h1>
<p>Today is <?= $format_as($date, 'date.long') ?></p>

Markdown Templates

# Hello !

Today is 

Advanced Usage

Custom Engine Configuration

$renderer = RendererFactory::create([
    'engines' => ['twig', 'markdown', 'pdf'],
    'paths' => ['/path/to/templates'],
    'formatters' => [
        'date' => function (string $date): string {
            $timestamp = strtotime($date);
            return date('d/m/Y', $timestamp);
        },
    ],
]);

Options

RendererFactory::create() takes these options:

A value of the wrong type in an option (a string where an array is expected, for example) is a translatable error that names the option and the type that it received.

Components

The Twig environment of the renderer has no components, so a tag <twig:...> is text for it. Give it the ones that the templates use, with the option components:

use Derafu\Renderer\Factory\RendererFactory;
use Derafu\Twig\Provider\DirectoryComponentProvider;

$vendor = __DIR__ . '/vendor/derafu/twig-components';

$renderer = RendererFactory::create([
    'paths' => [__DIR__ . '/templates', $vendor . '/resources/templates'],
    'components' => new DirectoryComponentProvider($vendor . '/src/Component'),
]);

The components are registered in the environment by derafu/twig, and the ones of derafu/twig-components are the UI components for websites.

Formatting in the Templates

The templates of the Twig and PHP engines have two helpers of the formatting system:

• format_as(value, format) formats the value with the handler of the format (the name of a handler, or handler.format).
• to_string(value) converts it to text: a scalar and null as text (null is empty), an object that can be a string as its text, and any other value, an array for example, as JSON.

<p>{{ date|format_as('date') }}</p>
<pre>{{ {'a': 1, 'b': [2, 3]}|to_string }}</pre>

In a PHP template they are the variables $format_as and $to_string, which are closures.

The Wrapper of the Markdown

The Markdown engine puts the HTML of the Markdown inside a Twig template, html by default, in the variable content. A different wrapper goes in the data or in the options with wrapperTemplate, and false (or null, in the engine) means no wrapper: the result is the HTML of the Markdown.

$renderer->render('page.md', ['wrapperTemplate' => 'article']);
$renderer->render('page.md', [], ['wrapperTemplate' => false]);