Collapse $scoped_vars + $mangled_vars into a single $vars param

Adds DEEPCLONE_HYDRATE_MANGLED_VARS flag. $vars is scoped per-class by
default; pass the flag to interpret it as the flat mangled-key array
(array) $obj produces. Mixed-mode (scoped + mangled merged in one call)
is removed — split into two calls if needed.

Footgun guard: a NUL-prefixed key at the top level of $vars in scoped
mode raises ValueError pointing at the missing flag.

Author: nicolas-grekas

CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### BC Break
+
+- `deepclone_hydrate()` now takes a single `$vars` array instead of
+  separate `$scoped_vars` and `$mangled_vars`. The default interpretation
+  is the scoped per-class shape; pass the new `DEEPCLONE_HYDRATE_MANGLED_VARS`
+  flag in `$flags` to interpret `$vars` as a flat mangled-key array (the
+  shape `(array) $object` produces). Old positional callers
+  (`deepclone_hydrate($obj, [], $mangled)`) need to be updated to
+  `deepclone_hydrate($obj, $mangled, DEEPCLONE_HYDRATE_MANGLED_VARS)`.
+  As a footgun guard, passing a NUL-prefixed key in scoped mode raises
+  a `ValueError` pointing at the missing flag.
+
+### Added
+
+- `DEEPCLONE_HYDRATE_MANGLED_VARS` constant — see BC break above.
+
 ### Changed
 
 - `deepclone_hydrate()` silently skips readonly writes when the target

README.md

@@ -63,7 +63,10 @@ $user = deepclone_hydrate(User::class, [
 ]);
 
 // Instantiate from class name with mangled keys (same format as (array) cast)
-$user = deepclone_hydrate(User::class, [], ['name' => 'Alice', 'email' => 'alice@example.com']);
+$user = deepclone_hydrate(User::class,
+    ['name' => 'Alice', 'email' => 'alice@example.com'],
+    DEEPCLONE_HYDRATE_MANGLED_VARS,
+);
 
 // Hydrate an existing object
 deepclone_hydrate($existingUser, ['User' => ['name' => 'Bob']]);
@@ -74,7 +77,7 @@ deepclone_hydrate($existingUser, ['User' => ['name' => 'Bob']]);
 ```php
 function deepclone_to_array(mixed $value, ?array $allowed_classes = null): array;
 function deepclone_from_array(array $data, ?array $allowed_classes = null): mixed;
-function deepclone_hydrate(object|string $object_or_class, array $scoped_vars = [], array $mangled_vars = [], int $flags = 0): object;
+function deepclone_hydrate(object|string $object_or_class, array $vars = [], int $flags = 0): object;
 ```
 
 `$allowed_classes` restricts which classes may be serialized or deserialized
@@ -83,19 +86,31 @@ function deepclone_hydrate(object|string $object_or_class, array $scoped_vars =
 the list.
 
 `deepclone_hydrate()` accepts either an object to hydrate in place or a class
-name to instantiate without calling its constructor. Both `$scoped_vars` and
-`$mangled_vars` can be used together; `$mangled_vars` values are resolved
-and merged into `$scoped_vars` before hydration. PHP `&` references are
-preserved in both.
+name to instantiate without calling its constructor. PHP `&` references in
+`$vars` are preserved through the hydrate.
 
-`$scoped_vars` is the **fastest path** — it writes directly to property
-slots with no key parsing, making it ideal for hot loops. It is keyed by
-declaring class name, each value being an array of property names to values.
+By default, `$vars` is keyed by declaring class name; each value is an array
+of property names to values. This is the fastest path — direct slot writes,
+no key parsing.
 
-`$mangled_vars` accepts the same mangled key format as `(array) $object`
-(`"\0ClassName\0prop"` for private, `"\0*\0prop"` for protected, bare name
-for public/dynamic). It resolves each key to the correct scope automatically,
-which is handy when round-tripping with `(array)` casts.
+```php
+$user = deepclone_hydrate(User::class, [
+    User::class => ['id' => 42, 'name' => 'Alice'],
+    AbstractEntity::class => ['createdAt' => new \DateTimeImmutable()],
+]);
+```
+
+Pass `DEEPCLONE_HYDRATE_MANGLED_VARS` in `$flags` to interpret `$vars` as a
+flat mangled-key array (the same shape `(array) $object` produces):
+`"\0ClassName\0prop"` for private, `"\0*\0prop"` for protected, bare name
+for public/dynamic. Each key is resolved to its scope automatically.
+
+```php
+$user = deepclone_hydrate(User::class,
+    ['name' => 'Alice', "\0User\0email" => 'alice@example.com'],
+    DEEPCLONE_HYDRATE_MANGLED_VARS,
+);
+```
 
 `$flags` selects the write semantics for declared-property assignments:
 
@@ -104,10 +119,11 @@ which is handy when round-tripping with `(array)` casts.
 | `0` (default)                          | `ReflectionProperty::setRawValue` — bypass set hooks, type-check, respect readonly |
 | `DEEPCLONE_HYDRATE_CALL_HOOKS`         | `ReflectionProperty::setValue` — invoke set hooks |
 | `DEEPCLONE_HYDRATE_NO_LAZY_INIT`       | `ReflectionProperty::setRawValueWithoutLazyInitialization` — skip the lazy initializer; realize the object when the last lazy property is set |
+| `DEEPCLONE_HYDRATE_MANGLED_VARS`       | interpret `$vars` as a flat mangled-key array (above) |
 
 `DEEPCLONE_HYDRATE_CALL_HOOKS` and `DEEPCLONE_HYDRATE_NO_LAZY_INIT` are
-mutually exclusive. `deepclone_from_array()` always uses the default
-setRawValue semantics, mirroring `unserialize()`.
+mutually exclusive; `MANGLED_VARS` composes with either. `deepclone_from_array()`
+always uses the default setRawValue semantics, mirroring `unserialize()`.
 
 ### Forgiving payload handling
 
@@ -140,19 +156,24 @@ strict-type errors. They run under every mode unless noted:
   enum-typed properties accordingly receive the enum case, not the
   raw scalar.
 
-The special `"\0"` key sets the internal state of SPL classes. In
-`$scoped_vars` it goes inside a scope entry; in `$mangled_vars` it is a
-flat key:
+The special `"\0"` key sets the internal state of SPL classes. In scoped
+mode it goes inside a scope entry; in `MANGLED_VARS` mode it is a flat key:
 
 ```php
-// Via $scoped_vars:
+// Scoped mode:
 $ao = deepclone_hydrate('ArrayObject', ['ArrayObject' => ["\0" => [['x' => 1]]]]);
 
-// Via $mangled_vars:
-$ao = deepclone_hydrate('ArrayObject', [], ["\0" => [['x' => 1], ArrayObject::ARRAY_AS_PROPS]]);
+// MANGLED_VARS mode:
+$ao = deepclone_hydrate('ArrayObject',
+    ["\0" => [['x' => 1], ArrayObject::ARRAY_AS_PROPS]],
+    DEEPCLONE_HYDRATE_MANGLED_VARS,
+);
 
 // SplObjectStorage: "\0" => [$obj1, $info1, $obj2, $info2, ...]
-$s = deepclone_hydrate('SplObjectStorage', [], ["\0" => [$obj, 'metadata']]);
+$s = deepclone_hydrate('SplObjectStorage',
+    ["\0" => [$obj, 'metadata']],
+    DEEPCLONE_HYDRATE_MANGLED_VARS,
+);
 ```
 
 ## What it preserves