HTML.PHP — Template Processing Library 🧩⚡

Production-grade PHP 8.3+/8.5 template engine with full Apache SSI directive support (#if expressions, #exec policies, #printenv, #block/stub), a gettext-compatible i18n layer (PO/MO/JSON/PHP catalogues, plural rules for 60+ languages, extraction & audit tooling), layout inheritance, scoped partials, a safe expression language — inline in substitutions since v5 (%{= a / b * 100}, nested/dynamic keys, get() indirection) — a render cache, a template linter, profiling stats, an optional WordPress bridge + maintenance toolkit, and a hardened escape-by-default security model with zero $GLOBALS, zero superglobal reads in the core, zero dependencies.

---

What's new in 5.0.0

Version 5 is an additive release: every 4.x template renders byte-identically. See docs/MIGRATION-4.x-TO-5.0.md.

	4.x	5.0
Math in a substitution tag	compute in @Set first	%{= done / total * 100 | round:1 }
Hash element by a dynamic key	❌ static dot paths only	%{= prices[currency]}, %{= rows[i].name}
Variable inside a variable	❌	%{= get(fieldName)}, %{= get('rows[1].name')}
Arithmetic filters	div only	add sub mul div mod pow sqrt pct sum avg clamp
Expression functions	17	23 (pow sqrt sum avg clamp get)
a..b ranges in expressions	broken (syntax error)	fixed, indexable: %{= (1..3)[1]}
Kill switch for inline math	—	syntax.expressions: false (fail-closed)

Hardening that came with it: bounded AST memo (4 096 FIFO), a 100 000-item iteration budget on every host-iterable walk, dynamic keys that can never reach an object property or method, get() paths that resolve against the scope stack only, and INF/NAN-free arithmetic. Inline expressions reuse the existing sandboxed evaluator — no eval, whitelisted functions only, auto-escaped output — so they add no new trust surface. Details: docs/SECURITY.md §4.

Upgrading

• From 4.x → 5.0: additive release, no breaking changes, no deprecations — docs/MIGRATION-4.x-TO-5.0.md.
• From 3.x: 4.0 was a clean-break rewrite — see the full mapping table in docs/MIGRATION-3.x-TO-4.0.md, then upgrade to 5.x. Release history: CHANGELOG.md.

Two editions

Edition	File	PHP	Language features
8.3 (portable)	php83/html.php	8.3 – 8.5+	typed class constants, readonly classes, enums
8.5 (modern)	php85/html.php	8.5+	everything above plus pipe operator |>, array_find(), property hooks, asymmetric visibility, #[\NoDiscard]

Both are generated from the same PSR-4 source tree (src/, with src-8.5/ overlays) by tools/build.php, and both pass the identical test matrix (386 tests / 1286 assertions per leg, run with and without ext-intl — the suite is extension-independent).

Installation

Option A — single file (no Composer): copy php83/html.php (or php85/html.php on PHP 8.5) into your project and require it. Done.

Option B — Composer (PSR-4 source):

composer require paulmann/html-php        # PHP 8.3/8.4
composer require paulmann/html-php85      # PHP 8.5

Option C — WordPress: install the bundled plugin in wordpress/html-php/ (see docs/WORDPRESS.md).

Quick start

require_once __DIR__ . '/php83/html.php';   // or Composer's autoloader

use HtmlPhp\Engine;
use HtmlPhp\Template\RenderOptions;

$engine = Engine::create([
    'templates' => ['paths' => [__DIR__ . '/templates']],
    'i18n'      => ['locale' => 'de', 'paths' => [__DIR__ . '/languages']],
    'cache'     => ['enabled' => true, 'driver' => 'file', 'directory' => sys_get_temp_dir() . '/htmlphp'],
]);

echo $engine->render('page.html', [
    'title' => 'Hello <World>',
    'rows'  => [['name' => 'Ada'], ['name' => 'Grace']],
]);

<!-- templates/page.html -->
<h1>%{title}</h1>                      <!-- auto-escaped: Hello &lt;World&gt; -->
<ul>
<!--@Loop rows-->
    <li>%{_position}. %{name|upper}</li>
<!--@Else-->
    <li>@{list.empty}</li>             <!-- translated when the list is empty -->
<!--@EndLoop-->
</ul>
<!--#include virtual="/partials/footer.shtml" -->   <!-- Apache SSI -->

The one-liner tour

$engine->renderString('%{price|number:2}', ['price' => 1234.5]);   // "1,234.50" (locale-aware)
$engine->renderString('%{= done / total * 100 | round:1 }%', $v);  // "14.8%" — inline math (v5)
$engine->renderString('%{= prices[currency]}', $v);                 // dynamic key (v5)
$engine->renderString('%{= get(fieldName)}', $v);                   // name from data (v5)
$engine->renderString('<!--@If total > 100 -->FREE<!--@Else-->%{ship|number:2}<!--@EndIf-->', $vars);
$engine->renderString('<!--@Set total="price * qty-->%{total|round:2}', $vars);
$engine->render('child.html');                 // <!--@Extends "base.html"--> inheritance
$engine->t('{0} files', [42]);                 // gettext with interpolation
$engine->processSsi($postContent);             // SSI over arbitrary strings (WP content!)
$engine->lintDirectory(__DIR__ . '/templates'); // CI-ready template validation
$engine->stats();                               // timings, loops, includes, cache hits

Architecture at a glance

Engine  ── facade: render / renderFile / renderString / lint / t / processSsi / stats
  │
  ├─ Config (immutable value object)      ├─ Container (PSR-11-shaped, lazy)
  ├─ Template\Renderer  ── pipeline: parse → layouts → tree render → SSI → cache
  │     ├─ TagParser → Node tree           ├─ TreeRenderer (loops/ifs/sections/partials)
  │     ├─ Substitution (%{} #{} @{} + filters)   ├─ Expression (safe evaluator)
  │     └─ Linter (reuses the parser)
  ├─ Ssi\Processor ── mod_include: scanner + DirectiveRegistry + policies
  ├─ I18n\Translator ── catalogues, plural forms, fallbacks, WP delegation
  ├─ Contracts\CacheInterface ── file/apcu/array/null/wp/psr16
  ├─ Log\LoggerInterface ── null/array/file/errorlog/syslog/wp/psr3
  ├─ Event\Dispatcher ── WP-hook-shaped tags & priorities
  ├─ Diagnostics ── capped structured collector (codes stable since 3.x)
  └─ WordPress\* ── Bridge, WpCache, WpLogger, TemplateLoader, Shortcodes,
                    AdminPage, Cli, Mailer + Maintenance toolkit (optional)

Hard rule enforced by the test suite (token-level scan): the core never calls eval() and never reads $GLOBALS/superglobals — the only sanctioned edge points are HtmlPhp\Input (explicit host-input helper) and the WordPress\* adapters (which exist to talk to WordPress).

Documentation

Document	Contents
docs/TEMPLATE-SYNTAX.md	substitutions, filters, loops, conditionals, layouts, partials, trans blocks
docs/SSI.md	every directive, expression grammar, exec policies, security
docs/I18N.md	catalogues, plural rules, extraction, audit, WordPress delegation
docs/API.md	full class/method reference
docs/CONFIGURATION.md	every config key, bounds and default
docs/WORDPRESS.md	bridge, plugin, maintenance toolkit, WP-CLI
docs/CLI.md	bin/htmlphp commands
docs/SECURITY.md	threat model & hardening guide
docs/ARCHITECTURE.md	layering, pipeline, editions, decisions
docs/MIGRATION-4.x-TO-5.0.md	4 → 5 upgrade: new syntax, hardening checklist
docs/MIGRATION-3.x-TO-4.0.md	1:1 mapping for every removed function
CHANGELOG.md	release history

Development

php8.3 tests/run.php                        # source tree
php8.5 tests/run.php --lib=php85/html.php   # 8.5 bundle
bash tools/run-matrix.sh                    # full matrix (8.3/8.4/8.5 × src/bundles)
php tools/build.php                         # regenerate both bundles
php tools/bench.php                         # throughput benchmark

CI (.github/workflows/ci.yml) runs the matrix, a bundle-drift check (build.php --check), PHPStan and PHP-CS-Fixer.

Requirements

PHP 8.3+ (8.5 edition: PHP 8.5+). No extensions required; mbstring improves truncation/slugs, intl improves transliteration, apcu enables the APCu cache driver.

License

MIT © Mikhail Deynekin — see LICENSE.