dhii/delimited-token-template

A flexible implementation for handlebars-style templates

v0.2.0-alpha2 2021-02-22 10:44 UTC

Requires

• php: ^7.1 | ^8.0
• dhii/output-renderer-interface: ^0.4-alpha1

Requires (Dev)

• phpunit/phpunit: ^6.0 | ^7.0 | ^8.0
• psr/container: ^1.0
• slevomat/coding-standard: ^6.0
• symfony/polyfill-php80: ^1.19
• vimeo/psalm: ^3.11.7 | ^4.0

MIT

• Anton Ukhanev

README

A flexible implementation for handlebars-style templates.

Details

This template implementation is useful if you need to replace simple tokens with values. Good examples are emails, which contain text like "Hello, %username%", or paths with variable segments, such as "/users/:username/profile".

The template supports any string delimiters: '[*placeholder*]', '~placeholder', and "{{placeholder}}" will all work. It's possible to have the left delimiter different from the right one, have delimiters which contain more than one character, or to even omit one of the delimiters.

When two delimiters are used, they can be escaped by a configurable escape character to make them be used literally in the rendered result. With the left and right delimiters being "{{" and "}}" respectively, and the escape char being "", the string "{{ {{username}}" could produce "{{ johnny" if rendered with context ['username' => 'johnny']. If the second left delimiter was escaped instead, i.e. "Hello, {{ {{username}}", rendering with [' {{username' => 'johnny'] would produce "Hello, johnny". This demonstrates that escaped delimiters will be replaced with their literal value in both the end result, and in token names.

Using one delimiter is also possible, e.g. "Hello, :username!" would produce "Hello, johnny!" when rendered with context ['username' => 'johnny']. In this case, however, contrary to using two delimiters, token names are limited to alphanumeric chars, as well as '_', '-', and '.' (underscore, dash, and period). In addition, it is not possible to escape delimiters. Consequently, token names cannot contain delimiters.

Usage

Two delimiters

This example uses two identical delimiters, and an escaped delimiter in the middle of the token name.

use Dhii\Output\DelimitedTokenTemplate\Template;

$template = new Template('Hello, %user\%name%!', '%', '%', '\\'); // Note escaped delimiter
$template->render(['user%name' => 'johnny']); // Hello, johnny! 

Different long delimiters

This example uses two different delimiters that are longer than 1 character, and of different lengths.

use Dhii\Output\DelimitedTokenTemplate\Template;

$template = new Template('Hello, -user\-name__!', '-', '__', '\\'); // Note completely different delimiters
$template->render(['user-name' => 'johnny']); // Hello, johnny! 

One delimiter with factory

Often times there will be some kind of convention within your application with regard to delimiters and the escape character. This these cases, it often useful to be able to instantiate several templates based on that standard, without having to specify it every time. The factory can represent that convention. This example uses tokens with only the left delimiter.

use Dhii\Output\DelimitedTokenTemplate\TemplateFactory;

$factory= new TemplateFactory(':', '', ''); // Note absence of right delimiter and escape character
$profilePath = $factory->fromString('/users/:username/profile')
    ->render(['username' => 'johnny']); // '/users/johnny/profile'
$settingsPath = $factory->fromString('/users/:userId/settings')
    ->render(['userId' => '1234']); // '/users/1234/settings'