littlecat-team/twigcat-extension

Unified TwigCat Twig 3.x extension: control flow, switch, safe regex, and portable PHP/Node digest, HMAC, and password compatibility functions.

dev-master 2026-08-06 04:37 UTC

Requires

• php: >=8.1
• twig/twig: ^3.19

MIT, BSD-3-Clause

• twig
• crypto
• regex
• compatibility
• switch
• password-hashing
• twigcat
• control-flow

Published on Packagist.org on 2026-08-06 04:40 UTC

README

A unified Twig 3.x extension for the PHP runtime. Registering this single extension enables all TwigCat compatibility surfaces.

Requirements

• PHP >= 8.1
• Twig >= 3.19

Installation

composer require littlecat-team/twigcat-extension

Registration

use TwigCat\Twig\TwigCatExtension;

$twig->addExtension(new TwigCatExtension());

No additional control-flow, regex, or switch extension registration is needed.

Features

Control-flow

• {% break %} and {% continue %}, with support for positive integer loop levels.
• {% goto name %} and {% label name %} with lexical validation and a fixed jump guard.
• {% switch %}, {% case %}, {% default %}, {% endswitch %}.

Regex

• regex_replace(pattern, replacement, limit = -1).
• regex_replace_callback(pattern, arrow, limit = -1).

regex_replace_callback only accepts a Twig arrow function when the callback is statically provided. If the callback comes from a spread argument, validation is deferred to runtime; string/array PHP callables and host closures are still rejected. Calls made inside a Twig arrow still use Twig's normal function resolver and remain subject to the Sandbox function policy.

Callback return values are restricted to scalar/null or Twig Markup.

Crypto & Password

• Legacy digest helpers md5(value, binary = false) and sha1(value, binary = false) — for existing data only.
• SHA-2 digest API: hash(algorithm, data, binary = false) for sha256/sha384/sha512, plus sha256(data, binary = false).
• HMAC/equality API: hash_hmac(algorithm, data, key, binary = false) for SHA-2 and hash_equals(known, user) (constant-time).
• Password API: password_hash, password_verify, password_needs_rehash, and password_get_info.
• Password globals: PASSWORD_DEFAULT, PASSWORD_BCRYPT, bcrypt default cost, and PASSWORD_ARGON2ID/Argon2 cost constants when the PHP runtime supports them. PASSWORD_ARGON2I is intentionally not exposed for new hashes.

hash() and hash_hmac() only accept SHA-256, SHA-384, and SHA-512. These map directly to PHP's hash()/hash_hmac(). md5() and sha1() are legacy helpers for existing digest-based data and must not be used for password storage.

No generic encrypt()/decrypt() or standalone bcrypt() alias is exposed. bcrypt is already represented unambiguously by password_hash(..., PASSWORD_BCRYPT).

All crypto helpers are regular Twig functions, so Twig Sandbox requires each function to be explicitly allow-listed before a sandboxed template can call it.

Password compatibility

The password functions are thin wrappers around PHP's native password API, not independent reimplementations. This preserves PHP's standard encoded hash formats with their embedded algorithm/cost/salt metadata. Existing hashes stored by a PHP application can be passed directly to password_verify().

{% set hash = password_hash(password, PASSWORD_DEFAULT) %}
{# `null` is accepted as an alias for PASSWORD_DEFAULT. #}
{% if password_verify(password, hash) %}
    valid
{% endif %}

New hashes are limited to bcrypt (PASSWORD_BCRYPT; PASSWORD_DEFAULT currently resolves to the same value) and Argon2id when the PHP runtime provides it. Argon2i and password_algos() are not exposed. password_verify() remains capable of verifying any password format supported by the running PHP runtime.