2026-01-06 23:29:10 +00:00
# Eyrie Templates
2025-12-12 21:01:19 +00:00
2026-01-06 23:29:10 +00:00
Eyrie is a fast, safe, and ergonomic server-side templating engine for PHP 8.2+. It is designed for the Phred Framework but can be used as a standalone library.
## Features
- **High-Performance:** Templates are compiled to native PHP code and cached.
- **Security-First:** Automatic output escaping by default to prevent XSS.
- **Minimal Syntax:** Clean and predictable syntax optimized for HTML.
- **DRY Composition:** Robust template inheritance and reusable components.
- **Expressive Control:** Support for conditionals, loops, and range-based iteration.
## Installation
Install Eyrie via Composer:
```bash
composer require getphred/eyrie
```
## Quick Start
```php
use Eyrie\Engine;
use Eyrie\Loader\FileLoader;
// 1. Configure the loader
$loader = new FileLoader(['./templates']);
// 2. Initialize the engine
$engine = new Engine($loader, [
'cache' => './cache',
'debug' => true,
]);
// 3. Render a template
echo $engine->render('welcome', ['name' => 'Phred']);
```
## Template Syntax
### Output
Use `<< >>` to output variables or expressions. All output is automatically escaped.
```html
< h1 > Hello, < < name > >!< / h1 >
< p > 2 + 2 = < < 2 + 2 > >< / p >
```
### Filters
Modify output using the pipe `|` operator.
```html
< p > < < title | upper > >< / p >
< p > < < bio | raw > >< / p > <!-- Use 'raw' to bypass auto - escaping (be careful!) -->
```
### Control Structures
Control blocks use the `<( )>` syntax.
#### Conditionals
```html
< ( if user.isAdmin )>
< p > Welcome, Admin!< / p >
< ( elseif user.isMember )>
< p > Welcome, Member!< / p >
< ( else )>
< p > Welcome, Guest!< / p >
< ( endif )>
```
#### Loops
```html
< ul >
< ( foreach item in items )>
< li > < < item > >< / li >
< ( endforeach )>
< / ul >
```
#### Range Loops
The `loop` tag provides a convenient way to iterate over a range. It also provides a `loop` variable with metadata.
```html
< ( loop from 1 to 5 )>
< p > Iteration < < loop.index > > of < < loop.length > >< / p >
< ( if loop.first )>First item!< ( endif )>
< ( if loop.last )>Last item!< ( endif )>
< ( endloop )>
```
### Template Inheritance
Eyrie supports powerful template inheritance using layouts and blocks.
#### Layout (`layouts/base.eyrie.php`)
```html
<!doctype html>
< html >
< head >
< title > [[ block title ]]My Site[[ endblock ]]< / title >
< / head >
< body >
< main >
[[ block content ]][[ endblock ]]
< / main >
< / body >
< / html >
```
#### Page (`home.eyrie.php`)
```html
[[ extends "layouts.base" ]]
[[ block title ]]Home Page - [[ super ]][[ endblock ]]
[[ block content ]]
< h1 > Welcome Home< / h1 >
[[ endblock ]]
```
### Components
Components are reusable pieces of UI that use a custom tag-like syntax.
```html
< @ Alert type="success" message="Operation successful!" />
```
### Template Resolution
Eyrie uses dot-notation to resolve template names relative to the configured loader paths.
```php
// Resolves to: ./templates/emails/welcome.eyrie.php
$engine->render('emails.welcome');
```
### Partials
Include other template files directly.
```html
[[ include "partials.header" ]]
```
## Configuration
### Loader
The `FileLoader` accepts an array of paths and an optional file extension (default is `.eyrie.php` ).
```php
$loader = new FileLoader(['./templates', './shared'], '.html');
```
### Engine Options
- `cache` : Path to the directory where compiled templates will be stored.
- `debug` : If `true` , templates are recompiled on every request (default `false` ).
## Advanced Usage
### Custom Helpers
You can register custom PHP functions to be used inside your templates.
```php
$engine->addHelper('greet', function($name) {
return "Hello, $name!";
});
```
Template:
```html
< < greet ( name ) > >
```
### Global Variables
Add variables that are available to all templates.
```php
$engine->addGlobal('app_name', 'My Eyrie App');
```
## License
MIT
