Download the PHP package enlivenapp/vision without Composer

Vision

Lightweight, framework-agnostic PHP template engine with auto-escaping, template inheritance, includes, filters, and custom tags.

Requirements

• PHP 8.1+

No framework dependencies. Works with any PHP project.

Installation

Quick Start

Create the engine once, optionally register any custom tags or filters your app needs, then render .tpl files:

That's the full lifecycle. The rest of this document covers template syntax and the engine API in detail.

Template Syntax

Vision templates are plain .tpl files. Four delimited constructs are recognized — everything outside them is emitted verbatim.

Output

{{ ... }} is the default output form. Results are passed through htmlspecialchars() with ENT_QUOTES | ENT_SUBSTITUTE and UTF-8, so output is safe by default:

If any step in a dot-notation chain is missing, the whole expression resolves to null silently.

Use {! ... !} when you intentionally want unescaped output (e.g. pre-rendered HTML from a trusted source):

Variables, literals, and expressions

Inside output and {% %} tags, Vision accepts:

• Variables — user, user.name, items.0.title
• String literals — 'hello' or "world" (either quote style; \ escapes the next character)
• Number literals — 42, 3.14
• Keyword literals — true, false, null

Conditionals

Branch on a truthy/falsy expression. elseif and else are optional.

Supported operators: ==, !=, >, <, >=, <=, and, or, not.

Vision uses its own truthiness rules — see Notes & Gotchas.

Loops

Iterate over any iterable value — arrays, Traversable objects, and generators all work:

If the value is not iterable, the loop body is skipped and emits nothing.

Filters

Filters transform a value using the | pipe syntax, and they chain left-to-right:

Built-in filters

Unknown filter names return the input unchanged — no error.

Custom filters

Custom filters receive the piped value as their first argument; any arguments in parentheses follow.

Custom tags

Custom tags are plain function calls inside a {% %} block — useful for URL helpers, site-wide values, translation lookups, and similar:

Arguments are whitespace-separated and may be any expression (literal, variable, filter chain). No tags are registered by default. Unregistered tags produce no output — no warning, no exception, no placeholder.

Template inheritance

Define a parent layout with one or more {% block %}...{% endblock %} regions:

layout.tpl

A child template declares {% extends %} and overrides whichever blocks it cares about:

page.tpl

Blocks the child does not override fall through to the parent's default content.

Includes

Pull one template into another:

Included templates inherit the parent's full variable scope. The optional with { key: value, ... } clause adds or overrides variables for the included template only — the parent's scope is not mutated.

Missing includes silently produce no output. When using the with clause, the template name must be a quoted string (see Notes & Gotchas).

The Engine API

new Engine()

Takes no arguments. Create one instance per application and reuse it.

Engine::render(string $templatePath, array $data, ?string $basePath = null): string

Returns the rendered string, or '' if $templatePath does not exist.

Set $basePath explicitly when your layouts or partials live in a different directory from the template being rendered — for example, a shared views/layouts/ tree referenced from module-local templates:

Engine::filters(): FilterRegistry

Returns the filter registry. Call ->register(string $name, callable $callback) to add custom filters.

Engine::tags(): TagRegistry

Returns the tag registry. Call ->register(string $name, callable $callback) to add custom tags.

File Extension

Templates use the .tpl extension by convention. Include and extends names have .tpl appended automatically if not present, so both {% include 'partials/sidebar' %} and {% include 'partials/sidebar.tpl' %} resolve to the same file.

Security

• Auto-escaping — all {{ }} output is escaped with htmlspecialchars() using ENT_QUOTES | ENT_SUBSTITUTE and UTF-8 encoding.
• Raw output is deliberate — unescaped output requires the distinct {! !} syntax, so it's never accidental.
• No PHP execution — templates cannot evaluate arbitrary PHP. The expression grammar only supports variable lookup, literals, comparisons, boolean logic, and registered filters/tags.
• Path-traversal protection — include and extends template names containing .. or null bytes resolve to empty and are never read from disk.
• Comments stripped at lex time — {# ... #} content is discarded before parsing and never reaches output.

Notes & Gotchas

These are the specific behaviors most likely to surprise you. Nothing here is a bug — each is intentional — but they're worth knowing up front.

• Truthiness is custom, not PHP-standard. Inside {% if %}, the values null, false, '', 0, '0', and [] are falsy; everything else is truthy. This matches most template engines.
• default does not treat 0 as empty. {{ count | default('none') }} renders 0 when count is zero, not 'none'. Only null, '', and false trigger the fallback. If you need a broader "emptiness" check, write a custom filter.
• Missing things fail silently. Missing variables resolve to null. Missing includes, missing extends parents, missing top-level templates, unregistered tags, and unknown filters all produce empty output with no warning. This keeps partial renders alive but means typos can go unnoticed — check your output, or wrap render() with your own logging if you need strictness.
• {% include ... with { ... } %} requires a quoted template name. {% include 'card' with {x: 1} %} works; {% include card with {x: 1} %} does not — the with clause is dropped and the name is taken literally. Plain includes without a with clause accept quoted or unquoted names.
• Only the first {% extends %} is honored. A template cannot extend multiple parents; any extra extends statements are ignored.
• The raw filter only matters as the last filter on {{ }}. {{ html | raw }} skips escaping. {{ html | raw | upper }} does not — the last filter is upper, not raw. For raw output, prefer the {! !} delimiter; it's clearer.
• nl2br output needs {! !}. {{ text | nl2br }} will escape the inserted <br> tags back into <br>. Use {! text | nl2br !} for the intended effect.
• .tpl is appended automatically. You don't need to include the extension in include / extends names unless you want to — both forms work.
• true, false, null are literals. {% if active == true %} and {{ value | default(null) }} treat these as PHP literals, not variable names.

Tests

See TESTS.md for the full test suite results covering output, escaping, conditionals, loops, filters, tags, includes, inheritance, literals, and security.

License

MIT