7.2. Handlebars Template Engine

• 7.2.1. Usage
• 7.2.2. Features
• 7.2.3. Production
• 7.2.4. API(12)

PHP Handlebars matches the JavaScript Version and has compile time helper support and super nice compile time error reporting. This version of Handlebars is based on caching the compiled templates and inherently made the overall compile times faster. Loading at ~50ms uncached and ~30ms cached.

7.2.1. Basic Usage

Rendering

use Cradle\Handlebars\HandlebarsHandler as Handlebars;
$handlebars = new Handlebars();
$template = $handlebars->compile('{{foo}} {{bar}}');

echo $template(['foo' => 'BAR', 'bar' => 'ZOO']);

Registering Helpers

$handlebars->registerHelper('bar', function($options) {
    return 'ZOO';
});

$template = $handlebars->compile('{{foo}} {{bar}}');

echo $template(['foo' => 'BAR']);

Registering Partials

$handlebars->registerPartial('bar', 'zoo');
$template = $handlebars->compile('{{foo}} {{> bar}}');

echo $template(['foo' => 'BAR']);

7.2.2. Features

• PHP API - designed to match the handlebars.js documentation
  • registerHelper() - Matches exactly what you expect from handlebars.js (except it's PHP syntax)
  • registerPartial() - accepts strings and functions as callbacks
  • Literals like {{./foo}} and {{../bar}} are evaluated properly
  • Comments like {{!-- Something --}} and {{! Something }} supported
  • Trims like {{~#each}} and {{~foo~}} supported
  • Mustache backwards compatibility {{#foo}}{{this}}{{/foo}}
  • Tokenizer helpers to optimize custom code generation to cache
  • Event handlers for unknown helpers and unknown partials
• Default Helpers matching handlebars.js
  • each - and {{#each foo as |value, key|}}
  • with
  • unless
  • if

7.2.3. Production Ready

When your templates are ready for a production (live) environment, it is recommended that caching be used. To enable cache:

• Create a cache folder and make sure permissions are properly set for handlebars to write files to it.
• Enable cache by using $handlebars->setCache(__DIR__.'/your/cache/folder/location');
• If the folder location does not exist, caching will be disabled.

7.2.4. API

• compile
• getCache
• getHelper
• getHelpers
• getPartial
• getPartials
• registerHelper
• registerPartial
• setCache
• setPrefix
• unregisterHelper
• unregisterPartial

compile

Returns a callback that binds the data with the template

Usage

$handlebars->compile(string $string);

Parameters

• string $string - the template string

Returns function - the template binding handler

Example

$handlebars->compile();

---

getCache

Returns the active cache path

Usage

$handlebars->getCache();

Returns Closure

---

getHelper

Returns a helper given the name

Usage

$handlebars->getHelper('if');

Parameters

• string $name - the name of the helper

Returns Closure

---

getHelpers

Returns all the registered helpers

Usage

$handlebars->getHelpers();

Parameters

Returns array

---

getPartial

Returns a partial given the name

Usage

$handlebars->getPartial('foobar');

Parameters

• string $name - the name of the partial

Returns string

---

getPartials

Returns all the registered partials

Usage

$handlebars->getPartials();

Parameters

Returns array

---

registerHelper

The famous register helper matching the Handlebars API

Usage

$handlebars->registerHelper(string $name, function $helper);

Parameters

• string $name - the name of the helper
• function $helper - the helper handler

Returns Eden\Handlebrs\Index

Example

$handlebars->registerHelper();

---

registerPartial

Delays registering partials to the engine because there is no add partial method...

Usage

$handlebars->registerPartial(string $name, string $partial);

Parameters

• string $name - the name of the helper
• string $partial - the helper handler

Returns Eden\Handlebrs\Index

Example

$handlebars->registerPartial();

---

setCache

Enables the cache option

Usage

$handlebars->setCache(string $path);

Parameters

• string $path - The cache path

Returns Eden\Handlebrs\Index

Example

$handlebars->setCache('/path/to/cache/folder');

---

setPrefix

Sets the file name prefix for caching

Usage

$handlebars->setPrefix(string $prefix);

Parameters

• string $prefix - Custom prefix name

Returns Eden\Handlebrs\Index

Example

$handlebars->setPrefix('special-template-');

---

unregisterHelper

The opposite of registerHelper

Usage

$handlebars->unregisterHelper(string $name);

Parameters

• string $name - the helper name

Returns Eden\Handlebars\Index

Example

$handlebars->unregisterHelper();

---

unregisterPartial

The opposite of registerPartial

Usage

$handlebars->unregisterPartial(string $name);

Parameters

• string $name - the partial name

Returns Eden\Handlebars\Index

Example

$handlebars->unregisterPartial();