Download the PHP package celema/boiler without Composer

Celema Boiler

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

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

Documentation

Start here: docs/index.md.

Topic overview

• Quick start
• Engine
• Rendering templates
• Displaying values
• Layouts
• Inserts
• Sections
• Slots
• Template

Quick start

Consider this example directory structure:

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

Then initialize the Engine and render your template:

Common patterns

Render from multiple directories, optionally with namespaces:

Control escaping:

Configure shared defaults and trusted classes:

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

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

Register custom filters with the fluent filter() method:

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 template.

Template helpers available via $this inside templates:

• $this->layout('layout')
• $this->insert('partial', ['value' => '...'])
• $this->slot(['value' => '...']) / $this->hasSlot() inside inserted templates that receive a closure or Slot::template() slot
• $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

Wrapped values are proxy objects, so === against a plain value is always false, and native string functions such as str_contains() silently operate on the escaped text. Compare and test through the proxy's predicate methods instead, which work on the raw value: $item->status->is(Status::Active), $status->in(['draft', 'pending']), $title->contains('&'), $url->startsWith('https://'), $file->endsWith('.pdf'), $slug->matches('/^[a-z0-9-]+$/'), and $tags->contains('featured') on wrapped arrays. See comparing wrapped values.

Error handling

Boiler fails fast on invalid lookups and render state, such as missing templates, invalid template names, duplicate layouts, unclosed sections, missing slots, or unknown methods and filters. See 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

For the PHP verification pipeline, run:

composer ci:full additionally lints Markdown and requires Node (npx).

License

This project is licensed under the MIT license.