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),
]);

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 }}

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'),
]);

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.