Template Loading

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 }}!', array('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(array(
    'loader' => new Mustache_Loader_FilesystemLoader(dirname(__FILE__) . '/views'),
));

// loads template from `views/hello_world.mustache` and renders it.
echo $m->render('hello_world', array('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 =  array('extension' => '.html');

$m = new Mustache_Engine(array(
    'loader' => new Mustache_Loader_FilesystemLoader(dirname(__FILE__) . '/views', $options),
));

Partials loading

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

<?php

$m = new Mustache_Engine(array(
    'partials' => array(
        'foo' => 'This is {{ foo }}',
        'bar' => 'Foo is not {{ bar }}',
    )
));

// loads the partial from our partials array:
echo $m->render('{{> foo }} ... {{> bar }}', array('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(array(
    'loader' => new Mustache_Loader_FilesystemLoader(dirname(__FILE__).'/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(array(
    'loader'          => new Mustache_Loader_FilesystemLoader(dirname(__FILE__) . '/views'),
    'partials_loader' => new Mustache_Loader_FilesystemLoader(dirname(__FILE__) . '/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(array(
    '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(dirname(__FILE__).'/views');
$tpl = $loader->load('foo'); // equivalent to `file_get_contents(dirname(__FILE__).'/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(array(
     'loader'          => new Mustache_Loader_FilesystemLoader(dirname(__FILE__).'/views'),
     'partials_loader' => new Mustache_Loader_FilesystemLoader(dirname(__FILE__).'/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, array(
    '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(array(
    new Mustache_Loader_InlineLoader(__FILE__, __COMPILER_HALT_OFFSET__),
    new Mustache_Loader_FilesystemLoader(__DIR__.'/templates')
));

String Loader

A String Loader is essentially a noop. 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(array('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.