182 lines
3.7 KiB
Markdown
182 lines
3.7 KiB
Markdown
# 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
|
|
<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
|