Drop scoped mode — mangled-only is now the only shape (v0.5.0)

The scoped shape `[$className => ['prop' => $val]]` and the flat mangled
shape `['prop' => $val, "\0Class\0priv" => $val2]` were functionally
equivalent: both resolved each key to the same `property_info` entry and
performed the same direct slot write. Keeping both required an
intermediate `scoped_props` HashTable built by the `MANGLED_VARS` path,
a double-pass write loop, and a footgun guard to catch users passing
mangled keys without the flag.

Drop scoped mode entirely. `$vars` is always the flat `(array)`-cast
shape, which is also what Doctrine-style ORM hydrators get from PDO.
The parser now writes directly during the key-parse pass — no
`scoped_props` accumulation, no second-pass loop.

### BC breaks

- Scoped-shape input `[$class => ['prop' => $val]]` is no longer
  understood. Callers migrate by flattening: bare names for public /
  protected / most-derived-private, `"\0Scope\0prop"` for
  parent-declared private.
- `DEEPCLONE_HYDRATE_MANGLED_VARS` constant removed (the mode is now
  implicit). Drop the flag from `$flags` arguments.
- `DEEPCLONE_HYDRATE_PRESERVE_REFS` moves from `1 << 3` to `1 << 2`,
  filling the slot vacated by `MANGLED_VARS`. Symbolic references via
  the constant name are unaffected.
- A mangled-form key (`"\0*\0prop"` or `"\0Class\0prop"`) that doesn't
  resolve to a declared slot on the resolved scope now raises
  `ValueError("key scope X does not declare a Y property")` instead of
  silently creating a dynamic property. A mangled-form key whose class
  name isn't `obj_ce` or a parent still raises the existing
  `"key scope X is not a parent of Y"` error.

### Code impact

- `deepclone.c`: -480 / +330 lines in `deepclone_hydrate()`. The
  scoped-mode second-pass write loop (~200 lines), the
  `MANGLED_VARS→scoped_props` intermediate builder (~140 lines), and
  the footgun guard are gone.
- `deepclone.stub.php` + regenerated `deepclone_arginfo.h`:
  `DEEPCLONE_HYDRATE_MANGLED_VARS` constant entry removed.
- `README.md`: rewritten the `$vars` section around the `(array)`-cast
  shape, with a table of key shapes and their targets. The "scoped
  mode" examples and the "which shape is faster" paragraph are gone.
- `CHANGELOG.md`: 0.5.0 entry documenting the BC break.
- `php_deepclone.h`: `PHP_DEEPCLONE_VERSION` `0.4.0` → `0.5.0`.

### Tests

All 30 phpt tests converted and passing locally on PHP 8.4 NTS. New
coverage:

- Bare name reaches a parent-private slot when the name is unambiguous.
- Mangled-form key with undeclared prop raises "does not declare"
  (`"\0*\0undeclared"` and `"\0Parent\0undeclared"` cases).

Author: nicolas-grekas

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this extension will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-04-15
+
+### BC Break
+
+- `deepclone_hydrate()` now interprets `$vars` exclusively as a flat
+  mangled-key array (the shape `(array) $obj` produces). The per-class
+  scoped shape (`[$class => ['prop' => $val]]`) is no longer supported —
+  callers passing the old shape will hit the `"invalid mangled key"` /
+  `"not a parent"` errors on NUL-prefixed keys, or silently create a
+  dynamic property named after the class on non-NUL keys. Migrate by
+  flattening: for each scope entry, use bare names for public / protected
+  / most-derived-private, and `"\0ScopeClass\0prop"` for parent-private
+  props. Motivation: the two shapes were functionally equivalent (same
+  resolution path, same slot writes), and keeping both required an
+  intermediate scoped_props HashTable + a double-pass write. Dropping
+  scoped mode simplifies the dispatcher into a single key-parse + write
+  loop, and removes ~200 lines of C.
+- `DEEPCLONE_HYDRATE_MANGLED_VARS` constant removed — flat mangled is
+  now the only mode, so the flag is redundant. Callers who were passing
+  the flag can simply drop it.
+- `DEEPCLONE_HYDRATE_PRESERVE_REFS` flag value changed from `1 << 3` to
+  `1 << 2` (filling the slot vacated by `DEEPCLONE_HYDRATE_MANGLED_VARS`).
+  Symbolic references via the constant name are unaffected; anyone using
+  the raw integer value `4` now gets `PRESERVE_REFS` instead of the old
+  `MANGLED_VARS` — in practice both are the flags real callers pass, so
+  the arithmetic happens to line up.
+
 ## [0.4.0] - 2026-04-15
 
 ### BC Break

README.md

@@ -56,27 +56,23 @@ properties — including private, protected, and readonly ones — without calli
 their constructor, faster than Reflection:
 
 ```php
-// Scoped array — keyed by declaring class
+// Flat bare-name array — ideal for hydrating from a flat row
+// (e.g. a PDO result).
 $user = deepclone_hydrate(User::class, [
-    User::class => ['id' => 42, 'name' => 'Alice'],
-    AbstractEntity::class => ['createdAt' => new \DateTimeImmutable()],
+    'id' => 42,
+    'name' => 'Alice',
+    'email' => 'alice@example.com',
 ]);
 
-// Flat bare-name array — ideal for hydrating from a flat row
-// (e.g. a PDO result), no scope grouping needed
-$user = deepclone_hydrate(User::class,
-    ['id' => 42, 'name' => 'Alice', 'email' => 'alice@example.com'],
-    DEEPCLONE_HYDRATE_MANGLED_VARS,
-);
-
-// Mangled keys (same format as (array) $obj cast)
-$user = deepclone_hydrate(User::class,
-    ['name' => 'Alice', "\0User\0email" => 'alice@example.com'],
-    DEEPCLONE_HYDRATE_MANGLED_VARS,
-);
+// Mangled keys for parent-declared private properties — same format as
+// (array) $obj cast produces.
+$user = deepclone_hydrate(User::class, [
+    'name' => 'Alice',
+    "\0AbstractEntity\0createdAt" => new \DateTimeImmutable(),
+]);
 
 // Hydrate an existing object
-deepclone_hydrate($existingUser, ['User' => ['name' => 'Bob']]);
+deepclone_hydrate($existingUser, ['name' => 'Bob']);
 ```
 
 ## API
@@ -97,40 +93,32 @@ name to instantiate without calling its constructor. By default, PHP `&`
 references in `$vars` are dropped on write; pass `DEEPCLONE_HYDRATE_PRESERVE_REFS`
 to keep them.
 
-By default, `$vars` is keyed by declaring class name; each value is an array
-of property names to values:
+`$vars` is a flat array keyed by property name — the exact shape
+`(array) $obj` produces:
 
-```php
-$user = deepclone_hydrate(User::class, [
-    User::class => ['id' => 42, 'name' => 'Alice'],
-    AbstractEntity::class => ['createdAt' => new \DateTimeImmutable()],
-]);
-```
+| key shape                   | target                                                    |
+|-----------------------------|-----------------------------------------------------------|
+| `"propName"`                | public, protected (any declaring class), or private declared on the object's own class |
+| `"\0*\0propName"`           | protected (the declaring class is resolved via the object) |
+| `"\0ClassName\0propName"`   | private declared on `ClassName` — must be the object's own class or a parent |
+| `"\0"`                      | SPL internal state (SplObjectStorage / ArrayObject / ArrayIterator) |
 
-Pass `DEEPCLONE_HYDRATE_MANGLED_VARS` in `$flags` to interpret `$vars` as a
-flat key array. Keys can be bare property names (auto-resolved to the
-declaring class, the ideal shape for hydrating from a PDO row), or
-mangled (`"\0ClassName\0prop"` for private, `"\0*\0prop"` for protected — the
-same shape `(array) $object` produces). The two forms can be mixed:
+Each key triggers one `properties_info` hash lookup followed by a direct
+slot write.
 
 ```php
-// Bare names — each is resolved to its declaring class automatically
-$user = deepclone_hydrate(User::class,
-    ['id' => 42, 'name' => 'Alice', 'email' => 'alice@example.com'],
-    DEEPCLONE_HYDRATE_MANGLED_VARS,
-);
-
-// Mangled keys, typical (array) cast shape
-$user = deepclone_hydrate(User::class,
-    ['name' => 'Alice', "\0User\0email" => 'alice@example.com'],
-    DEEPCLONE_HYDRATE_MANGLED_VARS,
-);
+$user = deepclone_hydrate(User::class, [
+    'id' => 42,                             // bare — public or own-private
+    'name' => 'Alice',
+    "\0*\0createdAt" => new \DateTimeImmutable(),    // protected
+    "\0AbstractEntity\0metadata" => [...],           // parent-private
+]);
 ```
 
-Both the scoped shape and the flat-bare-name shape take a direct
-`properties_info` lookup per key followed by a direct slot write — there's
-no meaningful performance difference between the two, pick whichever
-representation your caller already has on hand.
+Bare names are enough for every public, protected, or most-derived-private
+property. Parent-declared private properties need the explicit
+`"\0ClassName\0prop"` mangled form (the engine keys them that way in the
+child's `properties_info`).
 
 `$flags` selects the write semantics for declared-property assignments:
 
@@ -139,11 +127,10 @@ representation your caller already has on hand.
 | `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_PRESERVE_REFS`      | preserve PHP `&` references from `$vars` onto the target property slots; by default, references are dropped (dereferenced) on write |
 
 `DEEPCLONE_HYDRATE_CALL_HOOKS` and `DEEPCLONE_HYDRATE_NO_LAZY_INIT` are
-mutually exclusive; `MANGLED_VARS` and `PRESERVE_REFS` compose with either.
+mutually exclusive; `PRESERVE_REFS` composes with either.
 `deepclone_from_array()` always uses the default setRawValue semantics,
 mirroring `unserialize()`.
 
@@ -185,24 +172,18 @@ 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
-mode it goes inside a scope entry; in `MANGLED_VARS` mode it is a flat key:
+The special `"\0"` key sets the internal state of SPL classes:
 
 ```php
-// Scoped mode:
-$ao = deepclone_hydrate('ArrayObject', ['ArrayObject' => ["\0" => [['x' => 1]]]]);
-
-// 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']],
-    DEEPCLONE_HYDRATE_MANGLED_VARS,
-);
+// ArrayObject / ArrayIterator — ["\0" => [$array, $flags?, $iteratorClass?]]
+$ao = deepclone_hydrate('ArrayObject', [
+    "\0" => [['x' => 1, 'y' => 2], ArrayObject::ARRAY_AS_PROPS],
+]);
+
+// SplObjectStorage — ["\0" => [$obj1, $info1, $obj2, $info2, ...]]
+$s = deepclone_hydrate('SplObjectStorage', [
+    "\0" => [$obj, 'metadata'],
+]);
 ```
 
 ## What it preserves