Start drafting changelog (unfinished)

Author: theodorejb

CHANGELOG.md

@@ -3,6 +3,71 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.0.0] AST Compiler - 2026-03-22
+
+Rewrote the parser and compiler to use an AST, based on the same lexical analysis and grammar specification as Handlebars.js. This eliminates a large class of edge cases and parsing bugs that the old regex-based approach failed to handle correctly.
+
+### Added
+- Support for nested inline partials.
+- Support for closures in data and helper arguments.
+- `helperMissing` and `blockHelperMissing` hooks: handle calls to unknown helpers with the same API as in Handlebars.js, replacing the old `helperResolver` option.
+- `knownHelpers` compile option: tell the compiler which helpers will be available at runtime for more efficient execution (helper existence checks can be skipped).
+- `assumeObjects` compile option: a subset of `strict` mode that generates optimized templates when the data inputs are known to be safe.
+- Support for deprecated `{{person/firstname}}` path expressions for parity with Handlebars.js (please don't use this syntax in new code, though).
+
+### Changed
+- Custom helpers must now be passed when invoking a template (via the `helpers` runtime option key),
+  rather than at compile time. This is a significant optimization, since PHP files no longer have to be read and
+  tokenized to extract helper functions. It also enables sharing helper closures across multiple templates and renders,
+  and removes limitations on what they can access and do. Resolves https://github.com/zordius/lightncandy/issues/342.
+- Exceptions thrown by custom helpers are no longer caught and re-thrown, so the original exception can now be caught
+  in your own code for easier debugging (https://github.com/devtheorem/php-handlebars/issues/13).
+- `knownHelpersOnly` now works as in Handlebars.js: an exception will be thrown if the template uses a helper which is not in the `knownHelpers` list.
+- Updated various error messages to align with those output by Handlebars.js.
+- The `partialResolver` closure signature no longer receives a `Context` argument. Now only the partial name is passed.
+
+### Removed
+- `Options::$helpers`: pass custom helpers at runtime instead using the `helpers` key in the runtime options array (the second argument to the template closure).
+- `Options::$helperResolver`: use the `helperMissing` / `blockHelperMissing` runtime helpers instead.
+
+### Fixed
+- Fatal error with deeply nested `else if` using custom helper (https://github.com/devtheorem/php-handlebars/issues/2).
+- Incorrect rendering of float values (https://github.com/devtheorem/php-handlebars/issues/11).
+- Conditional `@partial-block` expressions.
+- Support for `@partial-block` in nested partials (https://github.com/zordius/lightncandy/issues/292).
+- Ability to precompile partials and pass them at runtime (https://github.com/zordius/lightncandy/issues/341).
+- Fatal error when a string parameter to a partial includes curly braces (https://github.com/zordius/lightncandy/issues/316).
+- Behavior when modifying root context in a custom helper (https://github.com/zordius/lightncandy/issues/350).
+- Escaping of block params and partial names.
+- Inline partials defined inside a `{{#with}}` or other block leaking out of that block's scope after it closes.
+- Numerous other bugs related to scoping, block params, inverted block helpers, section iteration, and depth-relative paths.
+
+
+Double-check every LightnCandy and PHP Handlebars issue where I left a comment, to see if any need to be updated following the helpers changes.
+
+Comment with fixed after release:
+- https://github.com/zordius/lightncandy/issues/342
+- https://github.com/zordius/lightncandy/issues/316
+- https://github.com/zordius/lightncandy/issues/350
+- https://github.com/zordius/lightncandy/issues/292
+- https://github.com/zordius/lightncandy/issues/341
+
+
+[Valid use for Lightncandy::prepare()](https://github.com/zordius/lightncandy/issues/346)
+- Comment that PHP Handlebars supports compile() method just like Handlebars.js
+
+
+[SafeString fails with FLAG\_EXTHELPER | FLAG\_BESTPERFORMANCE](https://github.com/zordius/lightncandy/issues/354)
+- Comment suggesting to try PHP Handlebars, which can often outperform LightnCandy without needing any special flags.
+
+- Support callable for helper functions: https://github.com/zordius/lightncandy/issues/228
+
+
+[Unable to resolve partial when using sub expression and partial resolver](https://github.com/devtheorem/php-handlebars/issues/5)
+- Maybe comment with approach using helper rather than partial?
+
+
+
 ## [0.9.9] Stringable Conditions - 2025-10-15
 ### Added
 - Allow `Stringable` variables in `if` statements ([#8](https://github.com/devtheorem/php-handlebars/pull/8)).
@@ -96,6 +161,7 @@ Initial release after forking from LightnCandy 1.2.6.
 - HTML documentation.
 - Dozens of unnecessary feature flags.
 
+[1.0.0]: https://github.com/devtheorem/php-handlebars/compare/v0.9.9...v1.0.0
 [0.9.9]: https://github.com/devtheorem/php-handlebars/compare/v0.9.8...v0.9.9
 [0.9.8]: https://github.com/devtheorem/php-handlebars/compare/v0.9.7...v0.9.8
 [0.9.7]: https://github.com/devtheorem/php-handlebars/compare/v0.9.6...v0.9.7

README.md

@@ -1,16 +1,26 @@
 # PHP Handlebars
 
-A blazing fast, spec-compliant PHP implementation of [Handlebars](https://handlebarsjs.com/).
+A blazing fast, spec-compliant PHP implementation of [Handlebars](https://handlebarsjs.com).
 
-Originally based on [LightnCandy](https://github.com/zordius/lightncandy), but rewritten to focus on
-more robust Handlebars.js compatibility without the need for excessive feature flags.
+Originally based on [LightnCandy](https://github.com/zordius/lightncandy), but rewritten to enable
+full Handlebars.js compatibility without excessive feature flags or performance tradeoffs.
+
+PHP Handlebars compiles and executes complex templates up to 40% faster than LightnCandy:
+
+| Library        | Compile time | Runtime | Total time | Peak memory usage |
+|----------------|--------------|---------|------------|-------------------|
+| LightnCandy    | 5.7 ms       | 2.8 ms  | 8.5 ms     | 5.3 MB            |
+| PHP Handlebars | 3.5 ms       | 1.6 ms  | 5.1 ms     | 3.6 MB            |
+
+_Tested on PHP 8.5 with the JIT enabled. See the `benchmark` branch to run the same test._
 
 ## Features
 
-* Compile templates to pure PHP code.
+* Supports all Handlebars syntax and language features, including expressions, subexpressions, helpers,
+partials, hooks, and `@data` variables.
 * Templates are parsed using [PHP Handlebars Parser](https://github.com/devtheorem/php-handlebars-parser),
-which implements the same lexical analysis and grammar specification as Handlebars.js.
-* Tested against the [Handlebars.js spec](https://github.com/jbboehr/handlebars-spec).
+which implements the same lexical analysis and AST grammar specification as Handlebars.js.
+* Tested against the full [Handlebars.js spec](https://github.com/jbboehr/handlebars-spec).
 
 ## Installation
 ```
@@ -55,7 +65,7 @@ $template = Handlebars::compile('Hi {{first}} {{last}}!', new Options(
     strict: true,
 ));
 
-echo $template(['first' => 'John']); // Error: Runtime: last does not exist
+echo $template(['first' => 'John']); // Error: "last" not defined
 ```
 
 ### Available Options
@@ -82,8 +92,8 @@ echo $template(['first' => 'John']); // Error: Runtime: last does not exist
 
 Helper functions will be passed any arguments provided to the helper in the template.
 If needed, a final `$options` parameter can be included which will be passed a `HelperOptions` instance.
-This object contains properties for accessing `hash` arguments, `data`, and the current `scope`, as well as
-`fn()` and `inverse()` methods to render the block and else contents, respectively.
+This object contains properties for accessing `hash` arguments, `data`, and the current `scope`, `name`,
+as well as `fn()` and `inverse()` methods to render the block and else contents, respectively.
 
 For example, a custom `#equals` helper with JS equality semantics could be implemented as follows:
 
@@ -94,17 +104,13 @@ $template = Handlebars::compile('{{#equals my_var false}}Equal to false{{else}}N
 $options = [
     'helpers' => [
         'equals' => function (mixed $a, mixed $b, HelperOptions $options) {
-            $jsEquals = function (mixed $a, mixed $b): bool {
-                if ($a === null || $b === null || is_string($a) && is_string($b)) {
-                    // In JS, null is not equal to blank string or false or zero,
-                    // and when both operands are strings no coercion is performed.
-                    return $a === $b;
-                }
-    
-                return $a == $b;
-            };
-    
-            return $jsEquals($a, $b) ? $options->fn() : $options->inverse();
+            // In JS, null is not equal to blank string or false or zero,
+            // and when both operands are strings no coercion is performed.
+            $equal = ($a === null || $b === null || is_string($a) && is_string($b))
+                ? $a === $b
+                : $a == $b;
+
+            return $equal ? $options->fn() : $options->inverse();
         },
     ],
 ];
@@ -164,3 +170,5 @@ with the following exceptions:
 
 * 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).
 * The `data` and `compat` compilation options have not been implemented.
+* The [runtime options to control prototype access](https://handlebarsjs.com/api-reference/runtime-options.html#options-to-control-prototype-access),
+along with the `lookupProperty()` helper option method have not been implemented, since they aren't relevant for PHP.