Skip to content

Commit 4563d15

Browse files
committed
Replace compile-time helpers with runtime helpers
Removed the `helpers` compilation option. All helpers must now be passed at runtime when executing the template. This enables sharing helpers across multiple templates, and removes limitations on what helpers can access and do. Also added `knownHelpers` option and updated `knownHelpersOnly` to work the same as in Handlebars.js.
1 parent 373a570 commit 4563d15

11 files changed

Lines changed: 853 additions & 1095 deletions

‎README.md‎

Lines changed: 27 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -62,14 +62,14 @@ echo $template(['first' => 'John']); // Error: Runtime: last does not exist
6262
```
6363

6464
**Available Options:**
65+
* `knownHelpers`: Associative array (`helperName => bool`) of helpers known to exist at template execution time. Passing this allows the compiler to optimize a number of cases. Builtin helpers are automatically included in this list.
6566
* `knownHelpersOnly`: Enable to allow further optimizations based on the known helpers list.
6667
* `noEscape`: Enable to not HTML escape any content.
6768
* `strict`: Run in strict mode. In this mode, templates will throw rather than silently ignore missing fields.
6869
* `assumeObjects`: Removes object existence checks when traversing paths. This is a subset of strict mode that generates optimized templates when the data inputs are known to be safe.
6970
* `preventIndent`: Prevent indented partial-call from indenting the entire partial output by the same amount.
7071
* `ignoreStandalone`: Disables standalone tag removal. When set, blocks and partials that are on their own line will not remove the whitespace on that line.
7172
* `explicitPartialContext`: Disables implicit context for partials. When enabled, partials that are not passed a context value will execute against an empty object.
72-
* `helpers`: Provide a key => value array of custom helper functions.
7373
* `partials`: Provide a key => value array of custom partial templates.
7474
* `partialResolver`: A closure which will be called for any partial not in the `partials` array to return a template for it.
7575

@@ -83,28 +83,30 @@ This object contains properties for accessing `hash` arguments, `data`, and the
8383
For example, a custom `#equals` helper with JS equality semantics could be implemented as follows:
8484

8585
```php
86-
use DevTheorem\Handlebars\{Handlebars, HelperOptions, Options};
86+
use DevTheorem\Handlebars\{Handlebars, HelperOptions};
8787

88-
$template = Handlebars::compile('{{#equals my_var false}}Equal to false{{else}}Not equal{{/equals}}', new Options(
89-
helpers: [
88+
$template = Handlebars::compile('{{#equals my_var false}}Equal to false{{else}}Not equal{{/equals}}');
89+
$options = [
90+
'helpers' => [
9091
'equals' => function (mixed $a, mixed $b, HelperOptions $options) {
9192
$jsEquals = function (mixed $a, mixed $b): bool {
92-
if ($a === null || $b === null) {
93-
// in JS, null is not equal to blank string or false or zero
93+
if ($a === null || $b === null || is_string($a) && is_string($b)) {
94+
// In JS, null is not equal to blank string or false or zero,
95+
// and when both operands are strings no coercion is performed.
9496
return $a === $b;
9597
}
96-
98+
9799
return $a == $b;
98100
};
99-
101+
100102
return $jsEquals($a, $b) ? $options->fn() : $options->inverse();
101103
},
102104
],
103-
));
105+
];
104106

105-
echo $template(['my_var' => 0]); // Equal to false
106-
echo $template(['my_var' => 1]); // Not equal
107-
echo $template(['my_var' => null]); // Not equal
107+
echo $template(['my_var' => 0], $options); // Equal to false
108+
echo $template(['my_var' => 1], $options); // Not equal
109+
echo $template(['my_var' => null], $options); // Not equal
108110
```
109111

110112
## Hooks
@@ -118,13 +120,13 @@ a helper that is not registered, even when the name matches a property in the cu
118120
For example:
119121

120122
```php
121-
use DevTheorem\Handlebars\{Handlebars, HelperOptions, Options};
123+
use DevTheorem\Handlebars\{Handlebars, HelperOptions};
122124

123-
$templateStr = '{{foo 2 "value"}}
124-
{{#person}}{{firstName}} {{lastName}}{{/person}}';
125+
$template = Handlebars::compile('{{foo 2 "value"}}
126+
{{#person}}{{firstName}} {{lastName}}{{/person}}');
125127

126-
$template = Handlebars::compile($templateStr, new Options(
127-
helpers: [
128+
$options = [
129+
'helpers' => [
128130
'helperMissing' => function (...$args) {
129131
$options = array_pop($args);
130132
return "Missing {$options->name}(" . implode(',', $args) . ')';
@@ -133,9 +135,9 @@ $template = Handlebars::compile($templateStr, new Options(
133135
return "'{$options->name}' not found. Printing block: {$options->fn($context)}";
134136
},
135137
],
136-
));
138+
];
137139

138-
echo $template(['person' => ['firstName' => 'John', 'lastName' => 'Doe']]);
140+
echo $template(['person' => ['firstName' => 'John', 'lastName' => 'Doe']], $options);
139141
```
140142
Output:
141143
> Missing foo(2,value)
@@ -150,7 +152,10 @@ Helpers may return a `DevTheorem\Handlebars\SafeString` instance to prevent esca
150152
When constructing the string that will be marked as safe, any external content should be properly escaped
151153
using the `Handlebars::escapeExpression()` method to avoid potential security concerns.
152154

153-
## Missing features
155+
## Missing Features
156+
157+
All syntax and language features from Handlebars.js 4.7.8 should work the same in PHP Handlebars,
158+
with the following exceptions:
154159

155-
All syntax from Handlebars.js 4.7.8 should work the same in this implementation, with the following exception:
156-
* Decorators ([deprecated in Handlebars.js](https://github.com/handlebars-lang/handlebars.js/blob/master/docs/decorators-api.md)) have not been implemented.
160+
* Custom Decorators have not been implemented, as they are [deprecated in Handlebars.js](https://github.com/handlebars-lang/handlebars.js/blob/master/docs/decorators-api.md).
161+
* The `data` and `compat` compilation options have not been implemented.

0 commit comments

Comments
 (0)