README

A standalone implementation of the Antlers templating engine, designed for use outside the Statamic/Laravel ecosystem in any PHP 8.2+ project.

По-русски

Positioning

antlers-php targets a standalone Antlers subset for regular PHP projects.

This means the project aims to support the core Antlers language that works predictably without Statamic or Laravel, such as variables, expressions, conditions, loops, modifiers, partials, and custom tags/modifiers.

It does not promise full compatibility with every Statamic tag, modifier, CMS feature, or Laravel-dependent integration.

In particular, {{? ?}} and {{$ $}} PHP delimiters from Statamic Antlers are intentionally not supported in antlers-php. This project keeps PHP execution out of the standalone core instead of exposing it as a template feature.

Installation

composer require bugo/antlers-php

Quick Start

use Bugo\Antlers\Engine;

$engine = new Engine();

echo $engine->render('Hello, {{ name }}!', ['name' => 'World']);
// → Hello, World!

Security

antlers-php does not auto-escape {{ ... }} output by default. This is intentional for standalone Antlers compatibility.

When rendering user-provided content into HTML, explicitly escape it with sanitize or entities:

{{ comment | sanitize }}
{{ email | entities }}

Treat plain {{ ... }} output as raw template output unless you have applied the escaping yourself.

Syntax

Variables

{{ name }}
{{ user.profile.name }}
{{ items[0] }}
{{ items[key] }}

items[key] uses the current scope variable key as the index. For a literal key, use dot notation: {{ items.key }}.

Null Coalescing and Ternary Operator

{{ name ?? "Guest" }}
{{ logged_in ? "Welcome back" : "Please log in" }}

Arithmetic and Strings

{{ price * 1.2 }}
{{ count + 1 }}
{{ "Hello" . ", " . name . "!" }}

Conditions

{{ if score > 90 }}
    Excellent!
{{ elseif score > 70 }}
    Good
{{ else }}
    Needs improvement
{{ /if }}

{{ unless logged_in }}
    <a href="/login">Log in</a>
{{ /unless }}

Loops

{{# foreach with alias #}}
{{ foreach items as item }}
    <li>{{ item.title }}</li>
{{ /foreach }}

{{# foreach with key and value #}}
{{ foreach data as key => value }}
    {{ key }}: {{ value }}
{{ /foreach }}

{{# statamic-compatible foreach forms #}}
{{ foreach:company_info }}
    {{ key }}: {{ value }}
{{ /foreach:company_info }}

{{ foreach:song_reviews as="song|rating" }}
    {{ song }}: {{ rating }}
{{ /foreach:song_reviews }}

{{ foreach :array="reviews:songs" as="song|rating" }}
    {{ song }}: {{ rating }}
{{ /foreach }}

{{# numeric loop #}}
{{ for 1 to 5 }}
    {{ value }}
{{ /for }}

{{# paired tag that iterates over an array #}}
{{ posts }}
    <h2>{{ title }}</h2>
{{ /posts }}

Variables available inside loops include:

Paired array loops also support neighbor access via colon notation:

{{ songs }}
    {{ value }} (next: {{ next:value }}, prev: {{ prev:value }})
{{ /songs }}

Modifiers

{{ title | upper }}
{{ title | lower | truncate:50 }}
{{ price | multiply:1.2 | round:2 }}
{{ items | sort | first }}
{{ date | format:"d.m.Y" }}

Setting Variables

{{ set greeting = "Hello" }}
{{ greeting }}, {{ name }}!

Comments

{{# This text will not appear in the HTML output #}}

{{? ?}} and {{$ $}} are not available in this engine. If you need PHP, keep it outside Antlers templates in your application code.

Noparse

{{ noparse }}
    {{ this will not be processed by the engine }}
{{ /noparse }}

Single tag: @{{ name }}

Tags

{{# self-closing tag #}}
{{ greeting name="Alice" }}

{{# tag with method (namespace) #}}
{{ partial:header title="Welcome" }}

{{# paired tag (with content) #}}
{{ markdown }}
**Bold**
{{ /markdown }}

Built-in Tags

The standalone core currently registers these built-in tags:

dump, foreach, increment, layout, loop, markdown, once, partial, prepend, push, scope, section, slot, stack, svg, switch, yield

set is also supported as Antlers syntax for variable assignment, but it is language syntax rather than a registered tag from CoreTags.

Core Tag Examples

{{ partial src="partials/card.antlers.html" title="Hello" }}
{{ partial:header title="Welcome" }}
{{ partial:exists src="partials/card.antlers.html" }}
{{ partial:if_exists src="partials/maybe.antlers.html" }}

{{ section:hero }}<h1>{{ title }}</h1>{{ /section:hero }}
{{ yield:hero }}
{{ yield:sidebar }}Fallback sidebar{{ /yield:sidebar }}

{{ markdown }}**Bold**{{ /markdown }}
{{ markdown:indent }}
    # Title
{{ /markdown:indent }}

{{ loop times="3" }}{{ value }}{{ /loop }}
{{ loop count="3" start="5" }}{{ value }}{{ /loop }}
{{ loop:2 }}{{ value }}{{ /loop:2 }}

{{ switch between="odd|even" }}
{{ switch name="rows" in="a|b" }}

{{ scope:page }}{{ page:title }}{{ /scope:page }}
{{ dump value=user }}
{{ svg src="icons/logo.svg" }}
{{ increment }}
{{ increment:row from="10" by="5" }}

Built-in Modifiers

This project intentionally supports an official subset of Statamic modifiers that works well in a standalone PHP engine, without Laravel/Statamic runtime dependencies.

Disputed Statamic Modifiers

antlers, partial, and raw are intentionally excluded from the standalone modifier API.

• partial stays a tag concern in this project: use partial, partial:exists, and partial:if_exists instead of a modifier.
• antlers is not part of the first stable standalone core because re-rendering strings as templates needs a separate execution model and explicit recursion safeguards.
• raw is not included because antlers-php does not auto-escape output by default; literal/raw behavior is already covered by normal output, @{{ ... }}, and noparse.

Extending

Custom Modifier

// Callable
$engine->addModifier('money', function(mixed $value, array $params, array $context): string {
    $currency = $params[0] ?? 'USD';
    return number_format((float) $value, 2) . ' ' . $currency;
});
// {{ price | money:EUR }}

// Class
use Bugo\Antlers\Modifiers\ModifierInterface;

class ExcerptModifier implements ModifierInterface
{
    public function modify(mixed $value, array $params, array $context): mixed
    {
        $length = (int) ($params[0] ?? 150);
        return mb_substr(strip_tags((string) $value), 0, $length) . '...';
    }
}

$engine->addModifier('excerpt', new ExcerptModifier());
// {{ content | excerpt:200 }}

Custom Tag

Built-in cache/nocache are not part of the required standalone core right now. If you need cache-like behavior, you can add it as a custom extension:

// Callable
$engine->addTag('icon', function(array $params): string {
    $name = $params['name'] ?? '';
    return "<svg class=\"icon\"><use href=\"#icon-{$name}\"></use></svg>";
});
// {{ icon name="star" }}

// Class with methods (namespace)
use Bugo\Antlers\Tags\AbstractTag;

class CacheTag extends AbstractTag
{
    public function index(): string|array|null
    {
        $key = $this->param('key', 'default');
        // ... cache logic
        return $this->content();
    }

    public function forget(): string|array|null
    {
        $key = $this->param('key', 'default');
        // ... clear cache
        return null;
    }
}

$engine->addTag('cache', new CacheTag());
// {{ cache key="homepage" }}...{{ /cache }}
// {{ cache:forget key="homepage" }}

Paired Tag with Children

$engine->addTag('repeat', function(array $params, array $data, $processor, $method, $children): string {
    $times  = (int) ($params['times'] ?? 1);
    $output = '';
    for ($i = 0; $i < $times; $i++) {
        $output .= $processor->reduce($children, array_merge($data, ['iteration' => $i + 1]));
    }
    return $output;
});
// {{ repeat times="3" }}{{ iteration }}. Hello!{{ /repeat }}

Global Variables

$engine->setGlobals([
    'site_name' => 'My Blog',
    'year'      => date('Y'),
    'user'      => $currentUser,
]);

// Available in all templates without passing them to render()
echo $engine->render('© {{ year }} {{ site_name }}');

Strict Mode

$engine->setStrictMode(true);

echo $engine->render('{{ name }}', ['name' => 'Alice']);
// Alice

echo $engine->render('{{ missing }}');
// throws AntlersRuntimeException