KD2 FW

Mustachier

Mustachier is a lightweight implementation of the Mustache template engine.

Supports all Mustache features, except lambdas and changing delimiters at runtime.

It is safe to use for user-templates, as it won't allow execution of any PHP code.

Performance

Mustache.php already performs quite well, but Mustachier is doing even better.

In benchmarks, Mustachier proved more than twice as fast and using 50 to 90% less memory than mustache.php.

For a simple Hello World this is the average results we've had for 1000 iterations:

  • Mustache PHP: running time 9 ms, memory usage 623 KB, 15 included files
  • Mustachier: running time 4 ms, memory usage 306 KB, 2 included files

PHP usage

Running Mustache code

You can run Mustache templates directly, there is no need to use files. This makes it ideal for user templates stored in a dynamic storage like a database. One example use would be an email template.

$mu = new \KD2\Mustachier;
$mu->render('{{name}}', ['name' => 'bohwaz']);

Will display:

bohwaz

You can also fetch the result of the template in a variable by setting the third parameter of render() to true:

$result = $mu->render('{{name}}', ['name' => 'bohwaz'], true);

Note that this use is not the best performance-wise as the template would be re-compiled and eval'd each time the script is called (but the compiled template is kept in cache for the current script execution, so the slowest time is the first call).

Using files as templates

For a more classic use of Mustache where templates are stored in the filesystem, this is how you should proceed:

$mu = new \KD2\Mustachier('/my/app/templates', '/tmp/app/compiled_templates');
$mu->display('welcome.mustache');

This will compile the /my/app/templates/welcome.mustache template in PHP code and store it in /tmp/app/compiled_templates/60b725f10c9c85c70d97880dfe8191b3, then it will include this file every time fetch() or display().

This is the best solution for large templates as the PHP opcache will be able to cache the file.

Fetch or display

To fetch the result of the template, use fetch() instead of display():

$result = $mu->fetch('welcome.mustache');

You can specify variables that will be available in the templates by either using assign() or by supplying an array as the second argument of display(), fetch() or render():

$mu->display('account.mustache', ['name' => 'bohwaz']);

is the same as:

$mu->assign(['name' => 'bohwaz']);
$mu->display('account.mustache');

Template syntax

Report to official doc

Unsupported features

The complete Mustache 1.0 specification is supported by Mustachier, but we decided against implementing some specific and rarely used features that would make the implementation too complex.

Set delimiter (core)

Delimiter change at runtime (eg. {{=<% }}=%>) is not supported, instead you can just change the default delimiters by extending the Mustachier class:

class My_Mustache extends \KD2\Mustachier {
     $delimiter_start = '<%';
     $delimiter_end = '%>';
}

Lambdas (module)

Mustache is a logic-less template engine, and lambdas make it having more logic than would be suitable.

Though any patch to include lambda support will be included if anyone wants to spend time on that, as long as the code is good.