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
• Inherited render context across layouts, inserts, and section captures; custom insert or layout context merges on top and overrides duplicate keys

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, including safe HTML helpers, and optional trusted classes

Installation

composer require celemas/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
• Engine
• Rendering templates
• Displaying values
• Layouts
• Inserts
• Sections
• Template

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 Celemas\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');

Configure shared defaults and trusted classes:

$engine = Engine::create(
    '/path/to/templates',
    defaults: ['siteName' => 'Celemas'],
    trusted: [TrustedHtml::class],
);

Register custom template methods with method(). Pass safe: true when a helper returns safe HTML:

use function App\Template\icon;

$engine = Engine::create('/path/to/templates')
    ->method('icon', icon(...), safe: true);

Methods are available as $this->icon() inside templates, inserts, and layouts.

Register custom filters with the fluent filter() method:

use Celemas\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 lower, upper, stripTags, and trim filters, and registers sanitize automatically when symfony/html-sanitizer is installed.

For filter safety rules and advanced wrapper, filter, and escaper customization, see displaying values, engine, and template.

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 on invalid lookups and render state, such as missing templates, invalid template names, duplicate layouts, unclosed sections, or unknown methods and filters. See rendering templates, layouts, sections, and template for the exact rules.

Benchmark

Boiler includes a canonical benchmark in bench/ that renders a feature-rich catalog page and is used mainly to catch performance regressions during development.

Run it with composer benchmark. For benchmark scope, caveats, and detailed usage, see bench/README.md.

Run the tests

composer test
composer lint
composer types
composer docs:lint

For the full verification pipeline, run:

composer ci

License

This project is licensed under the MIT license.