Release 1.2.0

Author: theodorejb

CHANGELOG.md

@@ -3,6 +3,27 @@ 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.2.0] Data Frames - 2026-03-30
+
+### Added
+- `Handlebars::createFrame()`: creates a child `@data` frame inheriting fields from a parent frame,
+  equivalent to `Handlebars.createFrame()` in Handlebars.js.
+
+### Changed
+- To align with Handlebars.js, `@data` variables passed to `fn()` or `inverse()` by block helpers are
+  no longer automatically merged with parent data and `@root`. For example, if a helper calls `fn()`
+  with `['data' => ['index' => 0]]` as the second parameter, `@index` will now be the *only* `@data`
+  variable inside the block. To set `@`-prefixed variables while still inheriting parent `@data`
+  variables, call `Handlebars::createFrame($options->data)` to create an isolated child frame.
+  Then assign new keys to it before passing it to the `data` option of `fn()` or `inverse()`.
+- `Handlebars::escapeExpression()` now uses `strtr()` instead of `str_replace()` for better performance.
+
+### Fixed
+- Block param path lookups and literal path lookups (e.g. `{{"foo"}}`, `{{#"foo"}}`) in `strict`
+  mode no longer incorrectly throw when the key exists but its value is `null`.
+- Inline partials defined inside an `{{else}}` block no longer leak into the surrounding scope.
+
+
 ## [1.1.0] Dynamic Partial Resolution - 2026-03-26
 
 ### Added
@@ -182,6 +203,7 @@ Initial release after forking from LightnCandy 1.2.6.
 - HTML documentation.
 - Dozens of unnecessary feature flags.
 
+[1.2.0]: https://github.com/devtheorem/php-handlebars/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/devtheorem/php-handlebars/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/devtheorem/php-handlebars/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/devtheorem/php-handlebars/compare/v0.9.9...v1.0.0

README.md

@@ -154,10 +154,9 @@ echo $template(['my_var' => null], $runtimeOptions); // Not equal
   (e.g. `{{#helper as |a b|}}` produces `2`).
 
 * `scope` (`mixed`): The current evaluation context (equivalent to `this` in a Handlebars.js helper).
-  Can be reassigned inside a helper to change the context passed to `fn()`.
 
-* `data` (`array`): The current `@data` frame. Contains `@`-prefixed private variables such as
-  `root`, `index`, `key`, `first`, `last`, and `_parent`. Can be read or modified inside a helper.
+* `data` (`array`): The current `@data` frame. `root` refers to the top-level context.
+  `index`, `key`, `first`, and `last` are set by `{{#each}}` blocks. Can be read or modified inside a helper.
 
 ### HelperOptions Methods
 
@@ -177,7 +176,7 @@ echo $template(['my_var' => null], $runtimeOptions); // Not equal
   remainder of the render. The closure must be produced by `Handlebars::compile`.
 
 > [!NOTE]  
-> `isset($options->fn)` and `isset($options->inverse)` return true if the helper was called as a block,
+> `isset($options->fn)` and `isset($options->inverse)` return `true` if the helper was called as a block,
 > and `false` for inline helper calls.
 
 ## Hooks
@@ -222,6 +221,13 @@ Helpers may return a `DevTheorem\Handlebars\SafeString` instance to prevent esca
 When constructing the string that will be marked as safe, any external content should be properly escaped
 using the `Handlebars::escapeExpression()` method to avoid potential security concerns.
 
+## Data Frames
+
+Block helpers that inject `@`-prefixed variables should create a child data frame using
+`Handlebars::createFrame($options->data)`, add their variables to it, and pass it to `fn()` or `inverse()`
+via the `data` key (e.g. `$options->fn($context, ['data' => $frame])`). This mirrors `Handlebars.createFrame()`
+in Handlebars.js, isolating the helper's variables while still inheriting parent data such as `@root`.
+
 ## Missing Features
 
 All syntax and language features from Handlebars.js 4.7.9 should work the same in PHP Handlebars,