omnibridge/twig

Installation

composer require omnibridge/twig

Under Symfony or Laravel the host bridge registers the extensions (Who registers what): nothing to do. Without a framework, give each extension the contracts it asks.

A page in plain PHP

<?php

require 'vendor/autoload.php';

use Omnibridge\Contract\Access;
use Omnibridge\Contract\Tokens;
use Omnibridge\Contract\Translations;
use Omnibridge\Contract\Urls;
use Omnibridge\Twig\AccessExtension;
use Omnibridge\Twig\ContractExtension;
use Twig\Environment;
use Twig\Loader\ArrayLoader;

$urls = new class implements Urls {
    public function path(string $name, array $parameters = []): string { return '/'.$name.'/'.implode('/', $parameters); }
    public function url(string $name, array $parameters = []): string { return 'https://example.org'.$this->path($name, $parameters); }
    public function asset(string $path): string { return '/build/'.$path; }
};
$translations = new class implements Translations {
    private const MESSAGES = ['article.read' => 'Lire « {title} »'];
    public function trans(string $id, array $parameters = [], ?string $domain = null, ?string $locale = null): string
    {
        return strtr(self::MESSAGES[$id] ?? $id, array_combine(array_map(static fn ($k) => '{'.$k.'}', array_keys($parameters)), $parameters));
    }
    public function exists(string $id, ?string $domain = null, ?string $locale = null): bool { return isset(self::MESSAGES[$id]); }
};
$access = new class implements Access {
    public function isGranted(mixed $attribute, mixed $subject = null): bool { return 'ROLE_ADMIN' === $attribute; }
    public function getUser(): ?object { return null; }
};
$tokens = new class implements Tokens {
    public function csrf(string $intent): string { return hash('sha256', 'session'.$intent); }
    public function isValid(string $intent, ?string $token): bool { return $token === $this->csrf($intent); }
};

$twig = new Environment(new ArrayLoader(['article.html.twig' => <<<'TWIG'
<a href="{{ path('article', {slug: 'le-fuji'}) }}">{{ 'article.read'|trans({title: 'Le Fuji'}) }}</a>
<link rel="canonical" href="{{ url('article', {slug: 'le-fuji'}) }}">
<link rel="stylesheet" href="{{ asset('app.css') }}">
{% if is_granted('ROLE_ADMIN') %}<form method="post"><input type="hidden" name="_token" value="{{ csrf_token('delete_12')|slice(0, 12) }}"></form>{% endif %}
TWIG]));
$twig->addExtension(new ContractExtension($urls, $translations));
$twig->addExtension(new AccessExtension($access, $tokens));
echo $twig->render('article.html.twig');

Its output (PHP 8.4, Twig 3, 2026-10-27):

<a href="/article/le-fuji">Lire « Le Fuji »</a>
<link rel="canonical" href="https://example.org/article/le-fuji">
<link rel="stylesheet" href="/build/app.css">
<form method="post"><input type="hidden" name="_token" value="e6a6fba63d4d"></form>

In a real host the contracts are the bridge's adapters (omnibridge/laravel's RouterUrls, CatalogueTranslations, GateAccess, SessionTokens), or Omnibridge\Runtime's: new ContractExtension(Runtime::urls(), Runtime::translations()).

Extensions

Three final classes extending Twig's AbstractExtension, in Omnibridge\Twig\.

ContractExtension

new ContractExtension(Urls $urls, Translations $translations)

Not marked safe: their output is escaped like any string (an address is safe to escape).

AccessExtension

new AccessExtension(?Access $access = null, ?Tokens $tokens = null)

Registered after twig-bridge's SecurityExtension and CsrfExtension under Symfony, so the same names answer through the contracts (and the same Symfony services). A contract not given leaves its function out: a template that calls it fails to compile ("Unknown function"), as it would under Symfony without SecurityBundle.

MapExtension

new MapExtension(
    MapPrinter $printer,          // omnimap's
    Urls $urls,
    ?Access $access = null,
    ?Tokens $tokens = null,
    string $control = 'ROLE_ADMIN',
    array $routes = [],           // ['export' => route name, 'suppress' => route name]
)

"May change the map" is Access::isGranted($control); false without an Access. Without Tokens the buttons carry an empty token. The constants MapExtension::EXPORT and MapExtension::SUPPRESS are the two intents, which the hosts' controllers check. The buttons post to the routes named by the host: under Symfony omnibridge/symfony's map cache routes; under Laravel routes the application declares itself (omnibridge/laravel routes the tile only, and names the others for the buttons).

{{ omnimap(view) }}
{{ omnimap_export(view, {class: 'item', text: 'Capture'}) }}
{{ omnimap_suppress(view, {text: 'Delete'}) }}

Helpers

HelperExtension: the small helpers omnibase gives the templates of its sites, for a framework rendering those templates without omnibase - the same names and results as omnibase's (Resources/Functions.php and FunctionTwigExtension), framework-free. omnibase registers this extension first and its own win where they do more; |at and |emoji_only are only here.

new HelperExtension(string $locale = 'fr', ?string $timezone = null)

$locale is the language of |lang_name and |datetime; $timezone the zone |datetime prints in (the date's own when null).

Function

Filters

HelperExtension::isMoment() is the ISO 8601 test |datetime uses (a date, a time, a zone or not).

A run

{{ 'Le mont Fuji, vu depuis le lac Kawaguchi au lever du jour'|str_shorten(20) }}
{{ 'Le mont Fuji, vu depuis le lac Kawaguchi au lever du jour'|str_shorten(20, 0) }}
{{ 'été'|mb_ucfirst }} {{ ['a', 'b', 'c']|second }} {{ ['a', null, 'c']|join_if_exists(', ') }}
{{ 'le mont Fuji'|highlight('Fuji') }}
{{ 'fr-FR'|lang }} {{ 'en-GB'|country }} {{ 'fr'|country }} {{ 'ja-JP'|lang_name }}
{{ '2026-04-10T18:05:00+00:00'|datetime('d MMMM YYYY HH:mm') }} {{ 'Présent'|datetime }}
{{ ['x', 'y']|at(1) }}{{ ['x', 'y']|at(5) is null ? ' (none)' }} {{ '👍 🎉'|emoji_only ? 'emoji' : 'text' }}
<div {{ html_attributes({class: 'card big', 'data-id': 12}) }}></div>
{{ 'ééééééééééééééééééééééééééééééééééééééééé'|str_shorten(10, -1) }}

With new HelperExtension('fr', 'Asia/Tokyo'), PHP 8.4 with intl, 2026-10-27:

Le mont Fuji, vu dep [..]
Le mont Fu [..] er du jour
Été b a, c
le mont <mark class="markdown-word"><mark class="markdown-pattern">Fuji</mark></mark>
fr GB FR japonais
11 avril 2026 03:05 présent
y (none) emoji
<div class="card big" data-id="12"></div>
[..] éééééééééé

• |str_shorten measures and cuts in characters (mb_strlen, mb_substr): 41 é shortened to 10 at the front keep their last ten.
• The moment 18:05 UTC is printed in Tokyo's time (03:05 the next day).
• |highlight is not marked safe: under autoescaping its marks are escaped, as the run shows. Write |highlight(...)|raw on a text that is already safe - the filter does not escape the text itself.

Testing

Testing a template

The extensions take the contracts as constructor arguments: a test gives them doubles, renders the template with Twig's ArrayLoader or FilesystemLoader, and compares the HTML - the Installation page's script is such a test. A template shared by two hosts is rendered by both and compared (lesringostars' parity suite does it for its pages).

The package's suite

The package has no Docker harness of its own: its suite runs in any PHP 8.2+ image with the checkout's vendor/ installed. With omnibridge/symfony's image (PHP 8.4, intl, GD):

docker run --rm --network none -v "$PWD":/package:ro omnibridge-symfony:php8.4 vendor/bin/phpunit --do-not-cache-result

The CI (GitHub Actions, glitchr-studio/ci's package workflow) runs PHPUnit and PHPStan at the highest level against phpstan-baseline.neon.

Verified, and not

What the tests prove

Run on 2026-10-27 in omnibridge-symfony:php8.4 (PHP 8.4.26, PHPUnit 11.5.57), the checkout's own vendor/, no network: 10 tests, 54 assertions, green (Testing).

The examples of this manual were run in the same image that day and their output pasted: the plain PHP page (Installation) and the helpers (Helpers).

Verified elsewhere

• Under Symfony: omnibridge/symfony's TwigTest (the functions are the contracts, answered as the framework's services, left out without security).
• Under Laravel: omnibridge/laravel's TwigAccessTest and OmnibaseTwigTest.
• lesringostars' article screen, one template rendered by both hosts (the pilot).

What is not verified

• Twig versions other than the one the checkout installs (composer.json admits 3.10 and later).
• A PHP without intl or mbstring: composer refuses to install the package (it requires both; Helpers).
• |less_than and |datetime around a change of time zone offset: not covered by the tests.