Match unserialize() permissiveness on scoped-mode property names

In scoped mode, the pre-v0.4.0 hot-path validation rejected any property
name that wasn't a string, contained a NUL byte, or looked like a mangled
key, with a ValueError. That was stricter than what `unserialize()` does
when it encounters the same shapes in an `O:…` payload:

- Integer keys: `unserialize()` coerces to string on dynamic property
  access (PHP's engine rule). The ext now iterates via ZEND_HASH_FOREACH_KEY_VAL
  and synthesises the string via `zend_long_to_str`.
- NUL-in-middle names: `unserialize()` stores them as-is on the dynamic
  property table. The ext drops the upfront `memchr` check on the stdClass
  write path and the dynamic-fallback write path, letting the engine store
  the raw name.
- NUL-prefix names: the engine native `Error` ("Cannot access property
  starting with \0") already surfaces from `zend_std_write_property` /
  `zend_hash_update`. No need for a pre-check.

DEEPCLONE_HYDRATE_MANGLED_VARS mode is unchanged — it still parses and
validates mangled keys as before (that's the entire point of the flag).

Besides the semantic alignment, this saves a hot-path validation per
written property — ~18 ns per prop in the polyfill, cheap in the ext but
the polyfill side is the real win.

Author: nicolas-grekas

CHANGELOG.md

@@ -26,6 +26,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   with `DEEPCLONE_HYDRATE_MANGLED_VARS`, `DEEPCLONE_HYDRATE_CALL_HOOKS`, and
   `DEEPCLONE_HYDRATE_NO_LAZY_INIT`.
 
+### Changed
+
+- `deepclone_hydrate()` scoped-mode property-name validation now matches
+  `unserialize()` permissiveness: integer keys coerce to strings on dynamic
+  property access; NUL-in-middle names are stored as raw dynamic properties
+  (same as `unserialize()` on an `O:…` payload with a NUL-containing key);
+  NUL-prefix names surface the engine's native `Error: Cannot access property
+  starting with "\0"`. The pre-v0.4.0 `ValueError` was stricter than
+  `unserialize()` and cost a per-prop validation in the hot path; dropping it
+  aligns the semantics and saves hot-path work. `DEEPCLONE_HYDRATE_MANGLED_VARS`
+  mode still parses and validates mangled keys.
+
 ## [0.3.1] - 2026-04-15
 
 ### Fixed

deepclone.c

@@ -3218,16 +3218,16 @@ PHP_FUNCTION(deepclone_hydrate)
 			EG(fake_scope) = scope_ce;
 		}
 
+		zend_ulong prop_idx;
 		zend_string *prop_name;
 		zval *prop_val;
-		ZEND_HASH_FOREACH_STR_KEY_VAL(Z_ARRVAL_P(scope_props), prop_name, prop_val) {
-			if (UNEXPECTED(!prop_name)) {
-				zend_value_error("deepclone_hydrate(): Argument #2 ($vars) scope \"%s\" must have only string keys",
-					ZSTR_VAL(scope_name));
-				EG(fake_scope) = old_scope;
-				if (scoped_owned) zval_ptr_dtor(&local_scoped);
-				zval_ptr_dtor(&obj_zval);
-				RETURN_THROWS();
+		ZEND_HASH_FOREACH_KEY_VAL(Z_ARRVAL_P(scope_props), prop_idx, prop_name, prop_val) {
+			/* Integer keys: coerce to string on dynamic property access, matching
+			 * unserialize()'s permissiveness. Allocated name is released below. */
+			bool prop_name_owned = false;
+			if (!prop_name) {
+				prop_name = zend_long_to_str((zend_long) prop_idx);
+				prop_name_owned = true;
 			}
 
 			/* "\0" key = internal state for ArrayObject/ArrayIterator/SplObjectStorage */
@@ -3292,15 +3292,9 @@ PHP_FUNCTION(deepclone_hydrate)
 			}
 
 			if (obj_ce == zend_standard_class_def) {
-				if (UNEXPECTED(memchr(ZSTR_VAL(prop_name), '\0', ZSTR_LEN(prop_name)) != NULL)) {
-					zend_value_error("deepclone_hydrate(): Argument #2 ($vars) scope \"%s\" contains an invalid property name; "
-						"use bare property names in scoped mode, or pass DEEPCLONE_HYDRATE_MANGLED_VARS in $flags",
-						ZSTR_VAL(scope_name));
-					EG(fake_scope) = old_scope;
-					if (scoped_owned) zval_ptr_dtor(&local_scoped);
-					zval_ptr_dtor(&obj_zval);
-					RETURN_THROWS();
-				}
+				/* Matches unserialize(): NUL-in-middle names are stored as-is,
+				 * NUL-prefix names are rejected by the engine on read. No
+				 * pre-validation — the polyfill follows the same rule. */
 				Z_TRY_ADDREF_P(prop_val);
 				zend_hash_update(obj->properties, prop_name, prop_val);
 			} else {
@@ -3317,31 +3311,27 @@ PHP_FUNCTION(deepclone_hydrate)
 				if (dc_is_backed_declared_property(pi)) {
 					bool ok = dc_write_backed_property(obj, pi, prop_name, prop_val, flags);
 					if (UNEXPECTED(!ok)) {
+						if (prop_name_owned) zend_string_release(prop_name);
 						EG(fake_scope) = old_scope;
 						if (scoped_owned) zval_ptr_dtor(&local_scoped);
 						zval_ptr_dtor(&obj_zval);
 						RETURN_THROWS();
 					}
 				} else {
-					/* Fallback: dynamic property or unknown name — validate first */
-					if (UNEXPECTED(memchr(ZSTR_VAL(prop_name), '\0', ZSTR_LEN(prop_name)) != NULL)) {
-						zend_value_error("deepclone_hydrate(): Argument #2 ($vars) scope \"%s\" contains an invalid property name; "
-							"use bare property names in scoped mode, or pass DEEPCLONE_HYDRATE_MANGLED_VARS in $flags",
-							ZSTR_VAL(scope_name));
-						EG(fake_scope) = old_scope;
-						if (scoped_owned) zval_ptr_dtor(&local_scoped);
-						zval_ptr_dtor(&obj_zval);
-						return;
-					}
+					/* Fallback: dynamic property or unknown name. Matches
+					 * unserialize(): the engine rejects NUL-prefix names with
+					 * \Error and accepts NUL-in-middle as raw dynamic props. */
 					zend_std_write_property(obj, prop_name, prop_val, NULL);
 					if (UNEXPECTED(EG(exception))) {
+						if (prop_name_owned) zend_string_release(prop_name);
 						EG(fake_scope) = old_scope;
 						if (scoped_owned) zval_ptr_dtor(&local_scoped);
 						zval_ptr_dtor(&obj_zval);
 						RETURN_THROWS();
 					}
 				}
 			}
+			if (prop_name_owned) zend_string_release(prop_name);
 		} ZEND_HASH_FOREACH_END();
 
 		EG(fake_scope) = old_scope;

tests/deepclone_hydrate.phpt

@@ -268,32 +268,30 @@ try {
     var_dump(str_contains($e->getMessage(), 'array values'));
 }
 
-// NUL byte in property name inside scoped array → ValueError
-try {
-    deepclone_hydrate('stdClass', ['stdClass' => ["foo\0bar" => 'val']]);
-} catch (\ValueError $e) {
-    var_dump(str_contains($e->getMessage(), 'invalid property name'));
-}
+// NUL-in-middle of a property name: matches unserialize() — accepted
+// as a dynamic property, the engine stores the raw name.
+$o = deepclone_hydrate('stdClass', ['stdClass' => ["foo\0bar" => 'val']]);
+var_dump(((array) $o)["foo\0bar"] === 'val');
 
-// NUL byte in mangled key property portion → ValueError
+// NUL byte in mangled key property portion → ValueError (MANGLED_VARS mode parses keys)
 try {
     deepclone_hydrate('stdClass', ["\0*\0foo\0bar" => 'val'], DEEPCLONE_HYDRATE_MANGLED_VARS);
 } catch (\ValueError $e) {
     var_dump(str_contains($e->getMessage(), 'invalid mangled key'));
 }
 
-// Integer key inside scoped array → ValueError
-try {
-    deepclone_hydrate('stdClass', ['stdClass' => [0 => 'val']]);
-} catch (\ValueError $e) {
-    var_dump(str_contains($e->getMessage(), 'string keys'));
-}
+// Integer key inside a scope: matches unserialize() — coerced to string
+// on dynamic property access.
+$o = deepclone_hydrate('stdClass', ['stdClass' => [0 => 'val']]);
+var_dump($o->{'0'} === 'val');
 
-// Mangled key inside scoped array → ValueError
+// Mangled-shape key inside a scope: engine rejects the NUL-prefix
+// property name with \Error. Callers wanting mangled keys pass
+// DEEPCLONE_HYDRATE_MANGLED_VARS.
 try {
     deepclone_hydrate('stdClass', ['stdClass' => ["\0stdClass\0x" => 'val']]);
-} catch (\ValueError $e) {
-    var_dump(str_contains($e->getMessage(), 'DEEPCLONE_HYDRATE_MANGLED_VARS'));
+} catch (\Error $e) {
+    var_dump(str_contains($e->getMessage(), 'starting with'));
 }
 
 // Interface as scope → ValueError
@@ -382,5 +380,4 @@ bool(true)
 bool(true)
 bool(true)
 bool(true)
-bool(true)
 Done