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

[nicolas-grekas]

Summary

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 no longer understood. [$class => ['prop' => $val]] is interpreted as a mangled-form input; a NUL-prefixed key that doesn't match a declared scope now raises "not a parent" / "does not declare" ValueError (see below), and a bare class name on stdClass silently creates a dynamic property named after the class. Callers migrate by flattening:

  // before
  deepclone_hydrate(User::class, [
      User::class => ['id' => 42, 'name' => 'Alice'],
      AbstractEntity::class => ['metadata' => [...]],
  ]);
  
  // after
  deepclone_hydrate(User::class, [
      'id' => 42,
      'name' => 'Alice',
      "\0AbstractEntity\0metadata" => [...],
  ]);

• 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.

• Mangled-form key → undeclared slot now rejects. A "\0*\0prop" or "\0Class\0prop" key that doesn't resolve to a declared property on its scope raises ValueError("key scope X does not declare a Y property") instead of silently creating a dynamic property. A mangled-form key whose class 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 (GP → P → C chain — 'secret' alone writes to GP::$secret, no mangled key required).
• Mangled-form key with undeclared prop raises "does not declare" ("\0*\0undeclared" on a user class and "\0Parent\0undeclared" on the child both rejected).

Test plan

• 30/30 .phpt tests green locally (PHP 8.4, NTS)
• CI green on the matrix (Linux NTS/ZTS/i386/debug, macOS, Windows)

Companion PR on symfony/polyfill (#576) mirrors this change — same BC breaks, same error messages, same test coverage.