Template loading - bobthecow/mustache.php GitHub Wiki

By default, \Mustache\Engine::loadTemplate and \Mustache\Engine::render calls accept your template passed as a string. For example:

<?php

$m = new \Mustache\Engine;

echo $m->render('Hello, {{ planet }}!', ['planet' => 'world']); // Hello, world!

You could load your template from the filesystem with a file_get_contents call, or load it from a database, or code it directly in your source as a string. While this is okay for trivial templates, it gets old really fast. To allow more advanced template lookups, Mustache supports template loaders.

The most common template loader is the Filesystem Loader. To load your Mustache template from the views directory of your project, you would add a Filesystem Loader and point it at the appropriate directory.

<?php

$m = new \Mustache\Engine([
    'loader' => new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views'),
]);

// loads template from `views/hello_world.mustache` and renders it.
echo $m->render('hello_world', ['planet' => 'world']);

By default, the Filesystem Loader appends a .mustache extension to the template you're attempting to load. You can configure the extension by passing an options array to the method.

<?php

// use .html instead of .mustache for default template extension
$options =  ['extension' => '.html'];

$m = new \Mustache\Engine([
    'loader' => new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views', $options),
]);

For local filesystem paths, the Filesystem Loader resolves requested template names and rejects anything outside the configured base directory, including path traversal and null-byte template names. To preserve the old behavior, set allow_unsafe_template_names to true:

<?php

$options = ['allow_unsafe_template_names' => true];

$m = new \Mustache\Engine([
    'loader' => new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views', $options),
]);

[!CAUTION] This disables path containment checks and is not recommended.

Partials loading

The most naïve partials loading is done with an Array Loader:

<?php

$m = new \Mustache\Engine([
    'partials' => [
        'foo' => 'This is {{ foo }}',
        'bar' => 'Foo is not {{ bar }}',
    ],
]);

// loads the partial from our partials array:
echo $m->render('{{> foo }} ... {{> bar }}', ['foo' => 'FOO', 'bar' => 'BAR']);

Like the String Loader used for normal templates, passing a partials array can get old really fast in all but the most trivial use cases.

If you supply a template loader to Mustache Engine, it will find partials using the same loader:

<?php

$m = new \Mustache\Engine([
    'loader' => new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views'),
]);

// `{{> foo }}` would look for a partial in `views/foo.mustache`

But partials aren't always in the same directory as first-class templates. A common project folder structure looks something like this:

project/
  views/
    foo.mustache
    partials/
      bar.mustache
      baz.mustache

Because our partials are in a views subdirectory, we have two options. We could either refer them as partials when we use them:

{{> partials/bar }}

... or we could add a second Filesystem Loader specifically for the partials:

<?php

$m = new \Mustache\Engine([
    'loader'          => new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views'),
    'partials_loader' => new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views/partials'),
]);

{{> bar }}

[!NOTE] To choose a partial name from the current context, see Dynamic names.

Available loaders

Array Loader

An Array Loader instance loads Mustache Template source by name from an initial array:

<?php

$loader = new \Mustache\Loader\ArrayLoader([
    'foo' => '{{ bar }}',
    'baz' => 'Hey {{ qux }}!'
]);

$tpl = $loader->load('foo'); // '{{ bar }}'

The Array Loader is used internally as a partials loader by \Mustache\Engine instance when an array of partials is set. It can also be used as a quick-and-dirty Template loader.

Filesystem Loader

A Filesystem Loader instance loads Mustache Template source from the filesystem by name:

<?php

$loader = new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views');
$tpl = $loader->load('foo'); // equivalent to `file_get_contents(__DIR__ . '/views/foo.mustache');

This is probably the most useful Mustache Loader implementation. It can be used for partials and normal Templates:

<?php

$m = new \Mustache\Engine([
     'loader'          => new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views'),
     'partials_loader' => new \Mustache\Loader\FilesystemLoader(__DIR__ . '/views/partials'),
]);

Production Filesystem Loader

A Production Filesystem Loader works like the Filesystem Loader, but returns template source objects with filesystem metadata for better compiled-template cache behavior. If a compiled template already exists in the cache and its source key is still valid, Mustache can reuse the compiled template without reading the template file again.

<?php

$m = new \Mustache\Engine([
    'cache'  => __DIR__ . '/cache/mustache',
    'loader' => new \Mustache\Loader\ProductionFilesystemLoader(__DIR__ . '/views'),
]);

By default, cache invalidation uses template file mtime and size. You can choose different stat() properties with stat_props, or disable stat-based invalidation entirely:

<?php

$loader = new \Mustache\Loader\ProductionFilesystemLoader(__DIR__ . '/views', [
    'stat_props' => null,
]);

[!CAUTION] If you disable stat-based invalidation, you must clear the template cache yourself when templates change. Make it part of your build or deploy process.

Inline Loader

With the Inline Loader, templates can be defined at the end of any PHP source file:

<?php

$loader  = new \Mustache\Loader\InlineLoader(__FILE__, __COMPILER_HALT_OFFSET__);
$hello   = $loader->load('hello');
$goodbye = $loader->load('goodbye');

__halt_compiler();

@@ hello
Hello, {{ planet }}!

@@ goodbye
Goodbye, cruel {{ planet }}

Templates are deliniated by lines containing only @@ name.

The Inline Loader is well-suited to micro-frameworks such as Silex:

<?php

// ...

$app->register(new MustacheServiceProvider, [
    'mustache.loader' => new \Mustache\Loader\InlineLoader(__FILE__, __COMPILER_HALT_OFFSET__)
]);

$app->get('/{name}', function($name) use ($app) {
    return $app['mustache']->render('hello', compact('name'));
})
->value('name', 'world');

// ...

__halt_compiler();

@@ hello
Hello, {{ name }}!

Cascading Loader

The Cascading Loader is a meta-Loader which delegates to other Loader instances. It is initialized with an array of loaders:

<?php

$loader = new \Mustache\Loader\CascadingLoader([
    new \Mustache\Loader\InlineLoader(__FILE__, __COMPILER_HALT_OFFSET__),
    new \Mustache\Loader\FilesystemLoader(__DIR__ . '/templates')
]);

String Loader

A String Loader is essentially a no-op. It simply passes the 'name' argument straight through:

<?php

$loader = new \Mustache\Loader\StringLoader;
$tpl = $loader->load('{{ foo }}'); // '{{ foo }}'

This is the default Template Loader instance used by Mustache:

<?php

$m = new \Mustache\Engine;
$tpl = $m->loadTemplate('{{ foo }}');
echo $tpl->render(['foo' => 'bar']); // "bar"

Advanced use

While the default Loader classes are great for almost every use case, you can create your own Mustache Loader that gets your template from anywhere. Just implement the \Mustache\Loader interface and pass your custom loader to the \Mustache\Engine.

This is an ideal place to hook in your project or framework's template loading logic. For example, the BobthecowMustacheBundle for Symfony uses a Symfony-compatible template loader.