README

Boiler is a small template engine for PHP 8.5+, inspired by Plates. Like Plates, it uses native PHP as its templating language rather than introducing a custom syntax.

Key differences from Plates:

Automatic escaping of strings and Stringable values for enhanced security
Global template context, making all variables accessible throughout the template

Other highlights:

Layouts, inserts/partials, and sections, including append and prepend support
Wrapper-driven escaping and a pluggable filter system for value transformations
Custom template methods and optional whitelisting of trusted value classes

Installation

composer require duon/boiler

Install Symfony's HTML sanitizer when you want Boiler's built-in sanitize filter:

composer require symfony/html-sanitizer

Documentation

Start here: docs/index.md.

Topic overview

Quick start

Consider this example directory structure:

path
`-- to
    `-- templates
        `-- page.php

Create a template file at /path/to/templates/page.php with this content:

<p>ID <?= $id ?></p>

Then initialize the Engine and render your template:

use Duon\Boiler\Engine;

$engine = Engine::create('/path/to/templates');
$html = $engine->render('page', ['id' => 13]);

assert($html === '<p>ID 13</p>');

Common patterns

Render from multiple directories, optionally with namespaces:

$engine = Engine::create([
    'theme' => '/path/to/theme',
    'app' => '/path/to/templates',
]);

// Renders the first match (theme overrides app)
$engine->render('page');

// Force a specific namespace
$engine->render('app:page');

Control escaping:

$engine = Engine::create('/path/to/templates');
$engine->render('page');
$engine->renderUnescaped('page');

$engine = Engine::unescaped('/path/to/templates');
$engine->render('page');
$engine->renderEscaped('page');

use Duon\Boiler\Contract\Filter;

$engine = Engine::create('/path/to/templates')
    ->filter('upper', new class implements Filter {
        public function apply(string $value, mixed ...$args): string
        {
            return strtoupper($value);
        }

        public function safe(): bool
        {
            return false;
        }
    });

Filters are available as virtual methods on wrapped string values in templates. In escaped renders, Boiler wraps string values for you. When you need filters on a raw value inside a template, call $this->wrap($value) first. Boiler ships with built-in sanitize and strip filters. If symfony/html-sanitizer is installed, the sanitize filter is registered automatically.

Use setWrapper() when you want to replace Boiler's runtime wrapper entirely. Use setFilters() and setEscapers() when you want Boiler to keep building the wrapper internally. These modes are mutually exclusive, and engine configuration is sealed on first wrapper() or render.

When Boiler manages escapers internally, you can register additional named escapers with Engine::escape().

Filter lookups use Duon\Boiler\Contract\Filters, which only needs a get(string $name): Duon\Boiler\Contract\Filter method. Filter registration is exposed separately through Duon\Boiler\Contract\RegistersFilters. Escaper registration is exposed separately through Duon\Boiler\Contract\RegistersEscapers.

Template helpers available via $this inside templates:

$this->layout('layout')
$this->insert('partial', ['value' => '...'])
$this->begin('name') / $this->append('name') / $this->prepend('name') / $this->end()
$this->section('name', 'default') / $this->has('name')
$this->unwrap($value) when you need the original value instead of the escaped wrapper
$this->escape($value) and $this->wrap($value) when you need proxy behavior such as string filters on a raw value

Error handling

Boiler fails fast when template lookup or render state is invalid. Common cases include:

missing template directories
missing templates or unknown namespaces
invalid template names such as malformed namespace:template paths
path traversal outside configured template roots
assigning more than one layout in the same template
nested or unclosed section capture blocks
calling an unknown filter or custom template method

See rendering templates, layouts, sections, and template for the relevant rules.

Benchmark

Boiler includes a canonical benchmark in bench/ that renders a feature-rich catalog page with layouts, repeated partials, sections or blocks, mixed array, object, and iterator view data, loops, and escaping.

The benchmark is meant to resemble a realistic steady-state page render and is used mainly to catch performance regressions during development.

Results depend on PHP version, OPcache settings, hardware, and workload shape. They do not represent every rendering scenario and should not be treated as universal rankings. If you want to evaluate Boiler for your environment, run the benchmark locally and compare it with your own templates.

Run the tests

composer test
composer lint
composer types
composer mdlint

For the full verification pipeline, run:

composer ci

License

This project is licensed under the MIT license.

duon / boiler

Maintainers

Package info

Statistics

Security