PHP Handlebars 无哈希助手实现方法

PHP Handlebars (salesforce/handlebars) 是一个用于解析和渲染 JavaScript Handlebars 模板的 PHP 库。虽然 JavaScript Handlebars 提供了块助手和非块助手两种类型的助手，但 PHP Handlebars 似乎原生不支持与 JavaScript Handlebars 语法完全一致的非块助手。本文将介绍一种修改 PHP Handlebars 核心文件的方法，以实现类似非块助手的功能。

问题背景

在 JavaScript Handlebars 中，非块助手可以直接在模板中使用，例如 {{helperName argument1 argument2}}。这种助手通常用于生成简单的 HTML 属性或文本片段。然而，在 PHP Handlebars 中，直接注册和使用这种类型的助手可能会遇到问题，特别是当需要在 PHP 和 JavaScript 环境中共享模板时。

解决方案：修改 Handlebars/Template.php

由于 PHP Handlebars 默认不支持非块助手，我们需要修改其核心文件 Handlebars/Template.php，在 variables 函数中添加自定义逻辑来处理这类助手。

具体步骤如下：

1. 定位 variables 函数: 打开 Handlebars/Template.php 文件，找到 private function variables(Context $context, $current, $escaped) 函数。

2. 添加自定义助手逻辑: 在该函数中，添加以下代码块，用于检测和处理非块助手：

    /* LS20211101 */
    /* Check for non-block helpers {{{ */
    // "Arguments" are subjected to a VERY simple parsing, with NO
    // syntax check. Just simple variables (plus @index and @key)
    // and strings between double quotes, parsed through
    // dirty base64 glomping.

    $words = preg_split('#\\s+#', $name, 2, PREG_SPLIT_NO_EMPTY);
    $code  = $words[0];
    if ($this->handlebars->hasHelper($code)) {
        $return = call_user_func_array(
            $this->handlebars->getHelper($words[0]),
            [
                $this,      // First argument is this template
                $context,   // Second is current context
                implode(
                    ' ',
                    array_map(
                        function ($token) use ($context) {
                            if ('"' === substr($token, 0, 1)) {
                                return base64_decode($token);
                            }
                            // If @data variables are not enabled, then revert back to legacy behavior
                            if ($token == '@index') {
                                return $context->lastIndex();
                            }
                            if ($token == '@key') {
                                return $context->lastKey();
                            }
                            return $context->get($token);
                        },
                        preg_split(
                            '#\\s+#',
                            preg_replace_callback(
                                '#"([^"]*)"#',
                                function ($matches) {
                                    return '"' . base64_encode($matches[1]) . '"';
                                },
                                $words[1]
                            ),
                            -1,
                            PREG_SPLIT_NO_EMPTY
                        )
                    )
                ),      // Arguments
                ''
            ]);
        if ($return instanceof String) {
            return $this->handlebars->loadString($return)->render($context);
        }
        return $return;
    }
    /** }}} end */

3. 代码解释:

   • 这段代码首先使用 preg_split 函数将变量名 $name 分割成助手名称 $code 和参数。
   • 然后，它检查 Handlebars 实例是否注册了名为 $code 的助手。
   • 如果助手存在，则使用 call_user_func_array 函数调用该助手，并将当前模板、上下文和参数传递给它。
   • 参数的解析使用了简单的字符串分割，并对双引号引起来的字符串进行了 base64 编码和解码，以便处理包含空格的字符串参数。
   • 最后，如果助手返回一个 String 对象，则将其渲染成字符串并返回。

示例：checked 助手

假设我们需要创建一个名为 checked 的非块助手，用于在复选框中添加 checked 属性。

1. 注册助手: 在 PHP 代码中，注册 checked 助手：

$handlebars = new HandlebarsEngine();
$handlebars->addHelper('checked', function ($template, $context, $value) {
    if ($value) {
        return 'checked="checked"';
    }
    return '';
});

2. 在模板中使用助手: 在 Handlebars 模板中使用 checked 助手：

<input name="acheckbox" {{checked record.acheckbox}} />

3. 渲染结果: 如果 $record['acheckbox'] 的值为 true，则渲染结果为：

<input name="acheckbox" checked="checked" />

否则，渲染结果为：

<input name="acheckbox"  />

注意事项

• 修改核心文件: 修改 Handlebars/Template.php 文件可能会导致与未来版本的 PHP Handlebars 不兼容。在升级库时，请务必重新应用此修改。
• 参数解析: 代码中参数解析逻辑非常简单，只支持变量和双引号字符串。更复杂的参数可能需要更复杂的解析逻辑。
• 安全性: 请注意转义助手返回的任何 HTML 代码，以防止跨站脚本攻击 (XSS)。
• 性能: 频繁调用 preg_split 和 base64_encode/decode 可能会影响性能。如果性能至关重要，请考虑优化代码。

总结

虽然 PHP Handlebars 官方库没有直接提供与 JavaScript Handlebars 完全一致的非块助手，但通过修改 Handlebars/Template.php 文件，我们可以实现类似的功能。这种方法允许我们在 PHP Handlebars 模板中使用自定义的非块助手，从而提高模板的灵活性和可重用性。然而，需要注意的是，修改核心文件可能会导致兼容性问题，并且需要谨慎处理参数解析和安全性问题。在实际应用中，请根据具体需求权衡利弊，选择最合适的解决方案。