Download the PHP package sailantis/clarity-engine without Composer

A fast, secure, and expressive PHP template engine – Maximum performance, whether sandboxed and secure or with the full power of PHP.

Features

• Compiled & Cached – Templates compile to PHP classes and leverage OPcache for blazing-fast rendering
• Secure Sandbox – No arbitrary PHP execution by default; templates are strictly sandboxed with controlled access
• Opt-In PHP Mode – Disable the sandbox to give templates the full power of PHP (any function call or filter, method calls, {% php %} blocks)
• Expressive Syntax – Clean, readable template syntax inspired by modern template engines
• Twig-Style Tests – in, is defined, starts with, matches, divisible by, and more, with absence-tolerant defined/null/empty
• Whitespace Control – {%- … -%} trims whitespace around a tag
• Loop Fallbacks – {% for %} … {% else %} … {% endfor %} renders the else branch when the sequence is empty
• Template Inheritance – Reusable layouts with extends and blocks for DRY template architecture
• Macros – Define reusable template fragments with parameters and call them inline
• Extensible — Custom filters, functions, inline filters, block directives, and loader plugins
• Modules – Bundle filters, functions, and directives into self-registering plug-ins
• Auto-escaping – Built-in XSS protection with context-aware automatic HTML/JS/CSS escaping
• Unicode Support – Full multibyte string handling with transparent normalization
• Zero Dependencies – Standalone engine with no external dependencies beyond PHP 8.2+

Installation

Requirements: PHP 8.2 or higher

Quick Start

Basic Setup

Your First Template

views/welcome.clarity.html:

That's it! Clarity automatically compiles and caches your template.

What a Template May Reach

Every template compiles under a policy: a set of capabilities plus two allowlists. The default is the most restrictive one, and the syntax is the same in all of them — only what a template may reach changes:

Policy::open() is the full-power PHP mode and is equivalent to executing arbitrary PHP. A Policy::custom() grant is a real grant too — see the security model and the policy reference.

Documentation

For Template Authors

Start here if you're writing templates:

• Getting Started – Installation, setup, and your first template
• Template Syntax – Variables, directives, operators, and control flow
• Filters & Functions – Transform data with built-in and custom filters
• Layout Inheritance – Reusable layouts with extends and blocks

For Developers

Integration and advanced topics:

• Advanced Topics – Namespaces, caching, auto-escaping, and Unicode
• Best Practices – Organization, security, performance, and testing
• Troubleshooting – Common errors and debugging techniques

Reference

• API Documentation – Auto-generated API reference for all classes
• Examples – Runnable template examples demonstrating features
• Guide Index – Complete documentation index

Output & Variables

Control Flow

Macros

Filters

Common filters: upper, lower, trim, length, number, date, sprintf, json, join, split, slug, map, filter, reduce, default, empty, striptags, escape, raw

See all filters and detailed syntax →

Template Inheritance

Includes

Full syntax reference →

Configuration

Configure the engine with these methods:

Configuration guide →

Security

Clarity is sandboxed by default:

• No arbitrary PHP execution – Templates cannot call PHP functions or access global state
• Auto-escaping by default – All output is HTML-escaped to prevent XSS attacks
• Compile-time validation – Syntax errors caught during compilation, not at runtime
• Object safety – Objects stay objects: a.b reads a public property and a:b reads an array key, so method calls are unreachable from templates and PHP visibility rules apply. Container operations read an object's public properties, and the date filter accepts DateTimeInterface directly
• Controlled lambdas – Lambda expressions can only use registered filters

Policies

What a template may reach is decided by a policy — a set of capabilities plus two allowlists, all resolved at compile time. The default is sandboxed and unreachable from PHP:

A policy that grants rawPhp, phpVariables or methodCalls is equivalent to executing arbitrary PHP and disables every guarantee listed above. Use it only for templates written and reviewed by trusted authors.

Templates record a digest of the policy that compiled them and are recompiled automatically when it changes — including when a single allowlist entry is added or removed. denyFunctions() adds guardrails on top of an open policy; nothing is denied by default, because an open policy is already the security decision.

The policy reference → Security best practices →

Performance

Clarity is designed for speed. Templates compile to native PHP classes and leverage OPcache for optimal performance:

• Compiled templates – One-time compilation to PHP, then served from OPcache
• Auto-invalidation – Cache automatically refreshed when templates change
• Zero runtime overhead – Inheritance resolved at compile time
• Minimal memory footprint – Efficient compilation with predictable memory usage

Benchmark Results

Clarity is measured against the other mainstream PHP template engines rendering the same page, on the same machine and PHP build. The two charts below are generated from the benchmark.

The dot is the median render and the caps bound the fastest observation and p95, so an engine that is usually fast but occasionally slow looks different from one that is uniformly slower.

Measured in a fresh process per engine, so no engine inherits another's footprint. The bar runs from the floor that engine costs to have loaded (left cap) to the peak it reached (right cap), and the dot is what it still holds once the run is done — the figure a serving process actually carries.

The full comparison — every shape, every chart, and the environment and engine versions this run recorded — is in the benchmark report, with the public version of the same data at https://sailantis.github.io/azera-competition/benchmarks/view-engine.html.

Performance optimization guide →

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Running Tests

Or run PHPUnit directly:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Documentation – Complete guide index
• Examples – Runnable example templates
• API Reference – Auto-generated API documentation
• GitHub Issues – Report bugs or request features

Built with ❤️ for developers who value security and performance