# Eyrie Templates
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
Hello, << name >>!
2 + 2 = << 2 + 2 >>
```
### Filters
Modify output using the pipe `|` operator.
```html
<< title | upper >>
<< bio | raw >>
```
### Control Structures
Control blocks use the `<( )>` syntax.
#### Conditionals
```html
<( if user.isAdmin )>
Welcome, Admin!
<( elseif user.isMember )>
Welcome, Member!
<( else )>
Welcome, Guest!
<( endif )>
```
#### Loops
```html
<( foreach item in items )>
- << item >>
<( endforeach )>
```
#### 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 )>
Iteration << loop.index >> of << loop.length >>
<( 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
[[ block title ]]My Site[[ endblock ]]
[[ block content ]][[ endblock ]]
```
#### Page (`home.eyrie.php`)
```html
[[ extends "layouts.base" ]]
[[ block title ]]Home Page - [[ super ]][[ endblock ]]
[[ block content ]]
Welcome Home
[[ 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