Release 1.3.0

Author: theodorejb

CHANGELOG.md

@@ -3,6 +3,24 @@ 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.3.0] Compat Mode - 2026-04-21
+
+### Added
+- `compat` compile option to enable recursive field lookup. When set to `true`, if a template variable is not
+  found in the current scope it will automatically be looked up in parent scopes, matching Mustache's behavior.
+- Official [Mustache spec](https://github.com/mustache/spec) tests are now run to verify `compat` functionality.
+
+### Changed
+- Slightly improved compiler performance by removing unnecessary internal state.
+- Optimized rendering of indented partials.
+
+### Fixed
+- Failure to invoke `@data` variables containing a closure when passed to `if` or `unless` helpers.
+- Hoisted block closures leaked into the caller's scope when a precompiled template was loaded via `include`/`require`.
+- Hash arguments passed to a partial were ignored when the partial was invoked in certain non-array contexts.
+- Block helpers returning a nested or non-list array were not stringified correctly.
+
+
 ## [1.2.3] Hoisted Closures - 2026-04-10
 ### Changed
 - Improved rendering performance by hoisting the closures for block bodies and `{{else}}` clauses,
@@ -20,14 +38,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   fixing numerous edge cases related to helpers and `@data` variables.
 
 ### Fixed
-- `../` expressions inside `{{else}}` blocks of `{{#if}}`, `{{#unless}}`, `{{#with}}`, and sections invoking `blockHelperMissing` resolved to the wrong context level.
-- A missing helper called via multi-segment path in a subexpression or `@data` variable failed to invoke `helperMissing`.
-- A non-function context property used as a helper (e.g. `{{foo "arg"}}` where `foo` is not a closure) incorrectly called `helperMissing` rather than throwing a distinct error.
+- `../` expressions inside `{{else}}` blocks of `{{#if}}`, `{{#unless}}`, `{{#with}}`,
+  and sections invoking `blockHelperMissing` resolved to the wrong context level.
+- A missing helper called via a `@data` variable or multi-segment path in a subexpression failed to invoke `helperMissing`.
+- A non-function context property used as a helper (e.g. `{{foo "arg"}}` where `foo` is not a closure)
+  incorrectly called `helperMissing` rather than throwing a distinct error.
 - No error thrown when calling a missing helper via a multi-segment path with arguments (e.g. `{{foo.bar "arg"}}`).
 - Closures in context data could not be used as block helpers (e.g. `{{#fn}}...{{/fn}}` where `fn` is a closure).
 - Closures in context data or `@data` variables failed to be passed `HelperOptions` as the last argument in certain cases.
 - Templates with hash arguments on complex paths (e.g. `{{foo.bar arg=val}}`) were not compiled correctly.
-- Closures in context data were not invoked when accessed via a multi-segment path (e.g. `{{foo.bar}}`), or via a literal path (e.g. `{{"foo"}}`) in `knownHelpersOnly` mode.
+- Closures in context data were not invoked when accessed via a multi-segment path (e.g. `{{foo.bar}}`),
+  or via a literal path (e.g. `{{"foo"}}`) in `knownHelpersOnly` mode.
 - `@data` variables incorrectly took priority over helpers with the same name.
 - `knownHelpersOnly` was not enforced for `@data` expressions or complex paths used with arguments.
 
@@ -245,6 +266,7 @@ Initial release after forking from LightnCandy 1.2.6.
 - HTML documentation.
 - Dozens of unnecessary feature flags.
 
+[1.3.0]: https://github.com/devtheorem/php-handlebars/compare/v1.2.3...v1.3.0
 [1.2.3]: https://github.com/devtheorem/php-handlebars/compare/v1.2.2...v1.2.3
 [1.2.2]: https://github.com/devtheorem/php-handlebars/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/devtheorem/php-handlebars/compare/v1.2.0...v1.2.1

README.md

@@ -10,7 +10,7 @@ PHP Handlebars compiles and executes complex templates over 40% faster than Ligh
 | Library            | Compile time | Runtime | Total time | Peak memory usage |
 |--------------------|--------------|---------|------------|-------------------|
 | LightnCandy 1.2.6  | 5.2 ms       | 2.8 ms  | 8.0 ms     | 5.3 MB            |
-| PHP Handlebars 1.2 | 3.2 ms       | 1.4 ms  | 4.6 ms     | 1.9 MB            |
+| PHP Handlebars 1.3 | 3.1 ms       | 1.4 ms  | 4.5 ms     | 1.9 MB            |
 
 _Tested on PHP 8.5 with the JIT enabled. See the `benchmark` branch to run the same test._
 
@@ -20,7 +20,7 @@ _Tested on PHP 8.5 with the JIT enabled. See the `benchmark` branch to run the s
 partials, hooks, `@data` variables, whitespace control, and `.length` on arrays.
 * Templates are parsed using [PHP Handlebars Parser](https://github.com/devtheorem/php-handlebars-parser),
 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).
+* Tested against the [Handlebars.js spec](https://github.com/jbboehr/handlebars-spec) and the [Mustache spec](https://github.com/mustache/spec).
 
 ## Installation
 ```
@@ -70,6 +70,9 @@ echo $template(['first' => 'John']); // Error: "last" not defined
 
 ### Available Options
 
+* `compat`: Set to `true` to enable recursive field lookup. If a template variable is not found in the current scope,
+  it will automatically be looked up in parent scopes, matching Mustache's default behavior.
+
 * `knownHelpers`: Associative array (`helperName => bool`) of helpers that will be registered at runtime.
   The compiler uses this to emit direct helper calls instead of dynamic dispatch, which is faster and required when `knownHelpersOnly` is set.
   Built-in helpers (`if`, `unless`, `each`, `with`, `lookup`, `log`) are pre-populated as `true` and may be excluded by setting them to `false`.
@@ -234,6 +237,6 @@ All syntax and language features from Handlebars.js 4.7.9 should work the same i
 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 `data` compilation option has 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.