Template Syntax

Template Syntax

HTML-first template language: every structural tag is an HTML comment, so templates remain valid markup and degrade gracefully in editors.

Note

Canonical spec: docs/TEMPLATE-SYNTAX.md. This page is the working guide — recipes first, edge cases in callouts.

Contents

1. Processing order
2. Substitutions
3. Filters
4. Loops
5. Conditionals & expressions
6. Set
7. Layout inheritance
8. Partials
9. Translation blocks
10. Raw & comments
11. Strictness

Processing order

flowchart LR
    A[source] --> B[parse → node tree]
    B --> C{extends?}
    C -- yes --> D[collect sections,\nrender parent chain ≤ 8]
    C -- no --> E[tree render\nloops·ifs·partials·set·trans\n+ %{} substitution]
    D --> E
    E --> F[SSI pass]
    F --> G{SSI emitted\ntemplate syntax?}
    G -- yes --> E2[one guarded re-render] --> H
    G -- no --> H[htmlphp.render filter → cache → out]

Loading

The parse tree is memoized per engine (LRU 512); identical sources parse once.

Substitutions

Form	Output
%{name}	variable, auto-escaped
%{user.address.city}	dot path: arrays → ArrayAccess → public props → label()/getLabel()/isLabel()/hasLabel()
%{name|upper|truncate:20:…}	filter chain
%{html|raw}	unescaped (policy: syntax.allow_raw_filter)
#{name}	identical alternate braces
@{page.title}	translation (catalogue → key itself as fallback)
{name}	only with syntax.single_braces: true

Anything inside braces that is not a valid name ([A-Za-z_][A-Za-z0-9_.-]*) is left untouched — CSS body { color: red } and JS if (x) { y() } survive.

Escaping rules (auto-escape is ON by default):

• HTML-escaped (ENT_QUOTES|ENT_HTML5|ENT_SUBSTITUTE, double_encode: false) unless the chain contains raw or ends in an escaping filter (escape/attr/url/json/js/css/nl2br).
• Missing names follow syntax.missing_var: empty (default, + diagnostic) · keep · placeholder · throw. null values are not missing — they render "" silently.

Filters

%{v|filter:arg:'quoted:arg'} — args split on :; quotes protect separators (|date:'H:i'); \ escapes inside quotes. Filters take & return mixed.

All 46 built-in filters (click to expand)

Group	Filters
Escaping	escape/esc/e[:strategy] · attr · url · json · js · css · raw
Text	upper · lower · ucfirst · title · words (count!) · trim[:chars] · pad[:len[:str[:left]]] · repeat[:n] · replace:from:to · truncate[:len[:suffix]] · excerpt[:len[:suffix]] · nl2br · striptags · slug[:sep]
Numbers	number[:dec[:point[:thousands]]] (locale-aware default) · round[:n] · cleanround[:n] · int · float · div:by (0 on zero divisor) · abs
Date/time	date[:format] · ago (clock-injected: "3 days ago")
Arrays/strings	join[:sep] · split:sep · length · first · last · reverse · sort[:desc] · unique · slice:offset[:len] · keys
Misc	default:value · translate[:…] · base64 · md5 · sha1

// custom filters are per-engine instances — no statics
$engine->filters()->add('money', fn(mixed $v): string => '€ ' . number_format((float) $v, 2));

Unknown filter → filter-unknown diagnostic + pass-through (or exception in syntax.strict).

Loops

<!--@Loop rows-->            row fields shadow outer scope; scalar = 1 row as %{value}
<!--@Loop item in rows-->    alias only
<!--@Loop k, v in map-->     key + value
<!--@Loop i in 1..10-->      inclusive range (either direction)
<!--@Else-->                 empty/missing iterable branch
<!--@EndLoop rows-->

Inside a row: _index (0-based) · _position (1-based) · _key · _first · _last · _count · _odd · _even · and the loop map (%{loop.index}, %{loop.length}, …). <!--@Break--> / <!--@Continue--> work anywhere inside (typically under an @If).

Iterables: arrays · Traversable · ArrayAccess&Countable · objects (public props) · scalars. Guards: limits.max_loop_rows (truncate + diagnose), limits.max_loop_depth.

<table>
<!--@Loop k, v in config-->
    <tr class="<!--@If _odd-->alt<!--@EndIf-->"><th>%{k}</th><td>%{v|escape}</td></tr>
<!--@Else-->
    <tr><td colspan="2">@{config.empty}</td></tr>
<!--@EndLoop-->
</table>

Conditionals & expressions

<!--@If total > 100 && currency == "EUR"-->Free shipping
<!--@Elif total > 0-->%{ship|number:2}
<!--@Else-->Checkout empty
<!--@EndIf-->

<!--@Unless user.hidden-->…<!--@EndUnless-->   <!-- = If !EXPR -->
<!--@If flag-->…<!--@EndIf-->                  <!-- v3-style truthiness still works -->

The expression language is a closed interpreter (no eval, ever):

Category	Available
Literals	numbers, 'strings', true/false/null
Names	scope vars, dot paths
Compare	== != === !== < <= > >= (numeric-aware)
Logic	&&/and · ||/or · !/not
Math	+ - * / % (÷0 → 0) · ~ concat
Choose	?: ternary · ?? coalesce
Sets	x in list · s matches '/re/' (literal patterns only)
Functions	count length empty defined min max abs round floor ceil int float str lower upper number default

Truthiness = PHP ('', '0', [], null, false are false). Broken expression → template-lint diagnostic + false branch (lenient) or TemplateSyntaxException (strict). ASTs are memoized — 10 000-row loops parse the condition once.

Set

<!--@Set total="price * qty + shipping"-->
<!--@Set label = 'Ready to ship'-->
%{total|number:2}

Writes into the current scope frame — inside a loop it dies with the iteration; the outer scope keeps its value.

Layout inheritance

<!-- layouts/base.html -->
<!doctype html>
<title><!--@Section title-->My Site<!--@EndSection--></title>
<main><!--@Section content-->Nothing here.<!--@EndSection--></main>

<!-- pages/checkout.html -->
<!--@Extends "layouts/base.html"-->
<!--@Section title-->%{shop} — Checkout<!--@EndSection-->
<!--@Section content-->
    <h1>@{checkout.heading}</h1>
    <!--@SectionParent-->            <!-- optional: keep parent default too -->
<!--@EndSection-->

• First @Extends wins; other top-level child output is dropped (Twig rule).
• Chains resolve deepest-override-first; @SectionParent steps one level down.
• Depth > 8 → TemplateException (cycle guard).

Partials

<!--@Include "parts/card.html"-->                    current scope inherited
<!--@Include "parts/card.html" with="title,url"-->   only listed vars (isolated)
<!--@Include "parts/card.html" only-->               empty scope
<!--@Include "parts/optional.html" ignore-missing--> silent when absent

Resolution: including document's directory → templates.paths → @namespace/ roots; default extension appended. Absolute paths, traversal and denied extensions are refused (Security). Missing without ignore-missing → TemplateNotFoundException.

Translation blocks

<!--@Trans-->Hello<!--@EndTrans-->                    static msgid "Hello"
<!--@Trans-->Hello %{name}<!--@EndTrans-->            msgid "Hello {0}" + arg
<!--@Trans count="%{n}" domain="shop" context="cart"-->
    %{n} item
<!--@Plural-->
    %{n} items
<!--@EndTrans-->

%{…} placeholders become positional {0}, {1}… — exactly what i18n:extract writes to the POT, so catalogues and templates agree by construction. {count} is available when count= is set. Args are escaped per the render's policy. → I18n Guide

Raw & comments

<!--@Raw--> %{not_a_var} <!--@If ignored--> <!--@EndRaw-->
<!--@Comment--> design note, never rendered <!--@EndComment-->

Strictness

Situation	Lenient (default)	syntax.strict: true
Unbalanced/unknown tags	always TemplateSyntaxException	same
Unknown filter	diagnostic + pass-through	exception
Broken condition expression	diagnostic + false	exception
Missing variable	per missing_var policy	typically throw

Tip

Don't discover any of this at runtime: bin/htmlphp lint templates/ catches all of it pre-deploy with file/line and CI exit codes. → CLI