README

安装

composer require g007/handlebars

简介

这是一个 PHP 实现的 Handlebars 模板，旨在匹配 JS 实现的接口。它不提供其他类似 PHP 库中的一些便利功能，例如从文件中加载模板。

这是从 Eden 框架中的 Handlebars 包分支出来的。它已被重构，不依赖于 Eden 核心包提供的魔法，并且不将大多数类视为单例。它还利用了 PHP 7 中可用的标量类型声明。

基本用法

实例化 Handlebars 类

Handlebars 对象有几个部分。首先是运行时对象。运行时最终包含所有助手和部分。它在编译模板时传递给模板，也用于编译期间的编译器。

use MattyG\Handlebars\Runtime;
$runtime = new Runtime();
// Pass false to the constructor to have it not load the default Helpers
$helperlessRuntime = new Runtime(false);

接下来，我们需要一个工厂来生成参数解析器。这本身需要一个工厂来生成参数列表。

use MattyG\Handlebars\Argument\ArgumentListFactory;
use MattyG\Handlebars\Argument\ArgumentParserFactory;
$argumentParserFactory = new ArgumentParserFactory(new ArgumentListFactory());

编译器有三个依赖项：运行时、生成标记解析器的工厂和生成参数解析器的工厂。每次编译新的模板时，都会使用标记解析器工厂创建一个新的标记解析器。在编译模板时，每当在模板中找到非部分标记时，都会使用参数解析器工厂创建一个新的参数解析器。

use MattyG\Handlebars\Compiler;
use MattyG\Handlebars\TokenizerFactory;
$compiler = new Compiler($runtime, new TokenizerFactory(), $argumentParserFactory);

最后，我们实例化实际的 Handlebars 对象。这是您将与之交互以注册助手和部分以及编译模板的对象。它有三个依赖项：运行时、编译器和生成数据对象的工厂。数据对象用于帮助轻松导航在渲染模板时提供的上下文。

use MattyG\Handlebars\DataFactory;
use MattyG\Handlebars\Handlebars;
$handlebars = new Handlebars($runtime, $compiler, new DataFactory());

建议您使用依赖注入系统来处理主 Handlebars 对象的构建，这样您只需要关注注册您的助手和部分以及实际编译您的模板。

或者，您可以使用新的便利函数，当您不关心替换任何组件时

use MattyG\Handlebars\Handlebars;
$handlebars = Handlebars::newInstance();

newInstance() 方法接受与 Runtime 构造函数相同的布尔参数，因此您仍然可以轻松防止自动添加默认助手。

渲染

$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'));

注册助手

$handlebars->registerHelper('bar', function($options) {
    return 'BAZ';
});
$template = $handlebars->compile('{{foo}} {{bar}}');
echo $template(array('foo' => 'BAR'));

注册部分

$handlebars->registerPartial('bar' => 'ABC');
$template = $handlebars->compile('{{foo}} {{> bar}}');
echo $template->render(array('foo' => 'BAR'));

功能

PHP API - 设计与 handlebars.js 文档相匹配
- registerHelper() - 与您从 handlebars.js 期望的完全匹配（除了它是 PHP 语法）
- registerPartial() - 接受字符串和函数作为回调
- 像 {{./foo}} 和 {{../bar}} 这样的文字会被正确评估
- 支持类似 {{!-- Something --}} 和 {{! Something }} 的注释
- 支持类似 {{~#each}} 和 {{~foo~}} 的缩进
- 与 Mustache 兼容的语法 {{#foo}}{{this}}{{/foo}}
- SafeString 类，允许助手返回 HTML
与 handlebars.js 匹配的默认助手
- if
- each - 以及 {{#each foo as |value, key|}}
- unless
- with

生产就绪

当您的模板准备在生产（实时）环境中使用时，建议使用缓存。要启用缓存

创建一个缓存文件夹，并确保为 handlebars 正确设置了写入文件的权限。
使用 $handlebars->setCachePath(__DIR__ . '/your/cache/folder/location'); 启用缓存
如果指定的文件夹不存在，代码将不会尝试创建该文件夹。

API

编译

返回一个包含供模板字符串编译后的代码的模板对象的模板。

用法

$template = $handlebars->compile(string $string);

参数

string $string - 模板字符串

返回 MattyG\Handlebars\Template 的一个实例 - 在模板对象上调用 render() 方法（或将其用作可调用的对象）来渲染。

示例

$template = $handlebars->compile('{{foo}} {{bar}}');
echo $template->render(array('foo' => 'FOO', 'bar' => 'BAR'));
// result: 'FOO BAR'

registerHelper

注册一个要在模板内使用的辅助函数。

辅助函数可以返回 SafeString 类的实例，以确保返回的内容不会被编译器转义。

注意，与 Handlebars 的 JS 实现不同，"this" 的概念在辅助函数内部并没有绑定到当前上下文。这实际上是一种自由：它允许你使用任何你想要的类型可调用的对象。

用法

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

参数

string $name - 辅助函数的名称
callable $helper - 辅助函数处理器

示例

$handlebars->registerHelper('baz', function() { return 'BAZ&BAZ'; });
$template = $handlebars->compile('{{foo}} {{baz}}');
echo $template(array('foo' => 'FOO'));
// result: 'FOO BAZ&amp;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

注册一个可重用的部分模板，用于在其他模板中。

用法

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

参数

string $name - 部分的名称
string $partial - 部分的模板字符串

示例

$handlebars->registerPartial('zoo', '1 + 2');
$template = $handlebars->compile('{{> zoo}} = {{result}}');
echo $template->render(array('result' => 3));
// result: '1 + 2 = 3'

setCachePath

启用编译模板的缓存。

用法

$handlebars->setCachePath(string $cachePath);

参数

string $cachePath - 存储编译模板缓存的路径

示例

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

setNamePrefix

设置编译模板的名称前缀。这用于在生成模板时避免冲突。

用法

$handlebars->setNamePrefix(string $namePrefix);

参数

string $namePrefix - 自定义前缀名称

示例

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

贡献

所有贡献都欢迎。理想情况下，所有代码贡献都将附带新的或更新的测试 :)

g007 / handlebars

维护者

详细信息