Download the PHP package wackowiki/templatest without Composer

Templatest

Push-style (with pull methods for e.g. csrf & i18n) lazy topo-ordered incremental building, liberated from von-neumann-style applicative transition template engine for WackoWiki.

Templatest is a lightweight, compiled template engine that separates presentation from logic. Templates are compiled once into an internal AST of patterns, variables, subpatterns and filters, then rendered by walking the AST and applying transformations on demand.

Features

• Compiled templates — parsed once, cached to disk, reused across requests
• Pattern blocks — define and recall named sections ([= name =] ... [=])
• One-off pattern definitions — [= abc def = ... =] for inline sub-templates
• Variables — [' var '] with optional filter pipes (| upper | default "anon")
• Subpatterns — [ ' name ' ] to embed pattern instances
• Pull actions — [ '' name: arg1 '' ] to call user-supplied functions at render time
• Filter pipeline — built-in filters for HTML/JS/CSS/URL escaping, string manipulation, dates, numbers, JSON encoding, and more
• Auto-indent — block tags automatically align with their surrounding context
• Pre-block support — special handling for <pre> and <textarea> content
• Escaper — context-aware escaping (HTML, HTML attribute, JS, CSS, URL) based on Zend Framework
• Pull-style extensibility — register runtime callbacks (CSRF tokens, i18n, etc.) that the template can invoke
• PHP 8.1+ strict typing — fully typed, namespaced, framework-independent
• No dependencies — zero Composer runtime dependencies; PHPUnit only for dev

Requirements

• PHP 8.1 or later
• iconv or mbstring extension (for non-UTF-8 encoding support in TemplatestEscaper)

Installation

Or, if vendoring manually:

Quick start

Template file hello.tpl

(Use [==== name ====] for visual emphasis — Templatest accepts any number of = signs.)

Rendering

Output

Template syntax

Quote convention

Templatest tags are wrapped in ' (apostrophe) characters. You can use one or more quotes on each side — the parser treats them as visual delimiters only. The minimum is one:

For nesting clarity, it's common to use more quotes for outer context and fewer for inner context, though this is purely cosmetic:

Equal signs in pattern markers

Pattern blocks use [= name =] or [==== name ====] — any number of = signs works:

All three are equivalent. Use whichever reads best.

Pattern definition

The first pattern defined in a file is the main pattern and is the one rendered by default.

Inline (one-off) pattern

Useful for small reusable chunks. The name may be a single punctuation character (anonymous) or an identifier.

Variables

Variables are assigned from PHP via $tpl->var_name = 'value' or via underscore-split paths.

Subpatterns

Embeds a pattern instance. Each invocation instantiates a fresh copy unless static inlining applies.

Pull actions

Invokes a user-registered PHP callback. The callback receives:

Filter pipes

Filters are evaluated left-to-right. The result of each filter is the input to the next.

Setup directives

Built-in filters

API reference

Templatest::read(string $filename, ?string $cache_dir = null): TemplatestUser

Compiles (or loads from cache) the template and returns a renderable instance.

• $filename — path to the template file
• $cache_dir — optional directory for cached compiled templates

TemplatestUser

Magic __set

The single-segment form ($tpl->name = ...) sets a top-level variable. The underscore form walks the pattern tree, so $tpl->items_item_text is equivalent to $tpl->set('items', 'item', 'text', value).

Magic __get

Returns the set-count for the chroot-prefixed variable name. Returns int, not an object — chained property access ($tpl->items->item->text) does NOT work; use the underscore-split form for both reading and writing.

Chroot context

Pull functions

Clone by pattern name

Direct invocation

set()

TemplatestEscaper

Context-aware escaping utilities, exposed via the escape filter:

Caching

Compiled templates are cached to disk if a $cache_dir is provided. The cache is invalidated when:

• the source file's mtime changes
• the cache file is missing or unreadable
• the cache file's CODE_VERSION doesn't match the running version

To disable caching for a single file, set its write bit off (chmod 644); Templatest will re-read from source each time.

To clear the entire cache:

Configuration

Setup directives (in .tpl files)

Default escape modes

TemplatestSetter::ESCAPER constant controls the default when a pattern has no explicit .escape directive. Default is 'raw' (no escaping).

Testing

Run with testdox formatting:

Run a single test:

Generate coverage (requires pcov or xdebug):

Architecture

Compilation pipeline

Render pipeline

Standalone helper utilities (Helper class)

Methods used internally that may also be useful on their own:

• Helper::join_path(...$parts): string|false
• Helper::serialize_data($data, $options = 0): string
• Helper::unserialize_data($text): mixed
• Helper::http64_encode($data): string
• Helper::is_empty($val): bool
• Helper::random_token($length = 10, $complexity = 2): string
• Helper::str_rand($min, $max): int
• Helper::qencode($name, $value): string
• Helper::stringify($x, $compact = 0, $full = 1): string|false
• Helper::dbg(...$args): void
• Helper::callee($class_filter): string

Credits

• Original WackoWiki templating engine by the WackoWiki team
• HTML escaper adapted from the BSD-licensed Zend Framework
• Standalone port and namespace cleanup by the Templatest maintainers

License

BSD-3-Clause — see LICENSE file.