djmattyg007 / handlebars
PHP implementation of Handlebars templates aiming to match the JS interface.
Installs: 10 811
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 4
Forks: 0
Open Issues: 0
Requires
- php: >=7.0.8
- ext-mbstring: *
Requires (Dev)
- phpunit/phpunit: 6.1.3
- psr/log: 1.0.2
README
Install
composer require djmattyg007/handlebars
Introduction
This is a PHP implementation of Handlebars templates that aims to match the interface of the JS implementation. It does not provide some of the niceties found in other similar PHP libraries, such as loading templates from files.
This is a fork of the Handlebars package from the Eden framework. It has been refactored to not rely on the magic provided by the Core package from Eden, and to not treat most of the classes as singletons. It also takes advantage of scalar type declarations available in PHP 7.
Basic Usage
Instantiating the Handlebars class
There are several parts to the Handlebars object. The first is the Runtime object. The Runtime is what ends up containing all helpers and partials. It is passed to Templates when they are compiled, and also the Compiler for use during compilation.
use MattyG\Handlebars\Runtime; $runtime = new Runtime(); // Pass false to the constructor to have it not load the default Helpers $helperlessRuntime = new Runtime(false);
Next, we need a factory to generate Argument Parsers. This itself requires a factory to generate Argument Lists.
use MattyG\Handlebars\Argument\ArgumentListFactory; use MattyG\Handlebars\Argument\ArgumentParserFactory; $argumentParserFactory = new ArgumentParserFactory(new ArgumentListFactory());
The Compiler has three dependencies: the Runtime, a factory to produce Tokenizers, and a factory to produce Argument Parsers. Each time a new Template is compiled, a new Tokenizer is created using the Tokernizer factory. While a template is being compiled, a new Argument Parser is created using the Argumetn Parser factory whenever a non-partial tag is found in the template.
use MattyG\Handlebars\Compiler; use MattyG\Handlebars\TokenizerFactory; $compiler = new Compiler($runtime, new TokenizerFactory(), $argumentParserFactory);
Finally, we instanstiate the actual Handlebars object. This is the object you'll be interacting with to register helpers and partials, and to compile templates. It has three dependencies: the Runtime, the Compiler, and a factory to produce Data objects. Data objects are used to help easily navigate the context provided when rendering a Template.
use MattyG\Handlebars\DataFactory; use MattyG\Handlebars\Handlebars; $handlebars = new Handlebars($runtime, $compiler, new DataFactory());
It is recommended that you use a dependency injection system to handle construction of the main Handlebars object, so that the only part you need to worry about is registering your helpers and partials, and actually compiling your templates.
Alternatively, you can use a new convenience function for when you don't care about swapping out any of the components:
use MattyG\Handlebars\Handlebars; $handlebars = Handlebars::newInstance();
The newInstance()
method accepts the same boolean parameter as the Runtime
constructor, so you
can still easily prevent the automatic addition of the default helpers.
Rendering
$template = $handlebars->compile('{{foo}} {{bar}}'); $content = $template->render(array('foo' => BAR, 'bar' =. 'ZOO')); // Or used as a callable $content = $template(array('foo' => 'BAZ', 'bar' => 'ABC'));
Registering Helpers
$handlebars->registerHelper('bar', function($options) { return 'BAZ'; }); $template = $handlebars->compile('{{foo}} {{bar}}'); echo $template(array('foo' => 'BAR'));
Registering Partials
$handlebars->registerPartial('bar' => 'ABC'); $template = $handlebars->compile('{{foo}} {{> bar}}'); echo $template->render(array('foo' => 'BAR'));
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}}
- SafeString class, to allow helpers to return HTML
- Default Helpers matching handlebars.js
- if
- each - and
{{#each foo as |value, key|}}
- unless
- with
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->setCachePath(__DIR__ . '/your/cache/folder/location');
- The code will not attempt to create the specified folder if it doesn't exist.
API
compile
Returns a template object containing the compiled code for the supplied template string.
Usage
$template = $handlebars->compile(string $string);
Parameters
string $string
- the template string
Returns an instance of MattyG\Handlebars\Template
- call render() on the template object (or use
it as a callable) to render it.
Example
$template = $handlebars->compile('{{foo}} {{bar}}'); echo $template->render(array('foo' => 'FOO', 'bar' => 'BAR')); // result: 'FOO BAR'
registerHelper
Register a helper to be used within templates.
Helpers can return an instance of the SafeString class to ensure that the returned content is not escaped by the compiler.
Note that unlike the JS implementation of Handlebars, the concept of "this" is not bound to the current context inside of a helper. This is actually a freedom: it allows you to use any type of callable you wish.
Usage
$handlebars->registerHelper(string $name, callable $helper);
Parameters
string $name
- the name of the helpercallable $helper
- the helper handler
Example
$handlebars->registerHelper('baz', function() { return 'BAZ&BAZ'; }); $template = $handlebars->compile('{{foo}} {{baz}}'); echo $template(array('foo' => 'FOO')); // result: 'FOO BAZ&BAZ'
use MattyG\Handlebars\SafeString; $handlebars->registerHelper('safehelper', function($value) { return new SafeString($value . '&BAZ'); }); $template = $handlebars->compile('{{foo}} {{safehelper 'BAR'}}'); echo $template->render(array('foo' => 'FOO')); // result: 'FOO BAR&BAZ'
registerPartial
Registers a reusable partial template for use within other templates
Usage
$handlebars->registerPartial(string $name, string $partial);
Parameters
string $name
- the name of the partialstring $partial
- the template string of the partial
Example
$handlebars->registerPartial('zoo', '1 + 2'); $template = $handlebars->compile('{{> zoo}} = {{result}}'); echo $template->render(array('result' => 3)); // result: '1 + 2 = 3'
setCachePath
Enables caching of compiled templates.
Usage
$handlebars->setCachePath(string $cachePath);
Parameters
string $cachePath
- The path to store cached copies of compiled templates
Example
$handlebars->setCachePath('/path/to/cache/folder');
setNamePrefix
Sets the name prefix for compiled templates. This is used to avoid conflicts when generating templates.
Usage
$handlebars->setNamePrefix(string $namePrefix);
Parameters
string $namePrefix
- Custom prefix name
Example
$handlebars->setNamePrefix('special-template-');
Contributing
All contributions are welcome. Ideally, all code contributions will come with new or updated tests :)