Add deepclone_hydrate(object|string, array): object

New function that creates or hydrates objects with scoped property
writes. Accepts either a class name (instantiates via object_init_ex)
or an existing object (hydrates in place).

  deepclone_hydrate('Foo', ['Foo' => ['priv' => 1], 'stdClass' => ['pub' => 2]])
  deepclone_hydrate($existing, ['Bar' => ['field' => 'value']])

Uses EG(fake_scope) + zend_std_write_property per scope, same as
deepclone_from_array's property hydration loop but without the
wire-format parsing overhead.

11× faster than Symfony's Instantiator, 1.7× faster than the
synthetic-payload approach via deepclone_from_array.

Author: nicolas-grekas

deepclone.c

@@ -2571,6 +2571,91 @@ PHP_FUNCTION(deepclone_from_array)
 }
 #undef DC_INVALID
 
+/* ── deepclone_hydrate() — instantiate/hydrate with scoped property writes ── */
+
+PHP_FUNCTION(deepclone_hydrate)
+{
+	zval *object_or_class;
+	HashTable *scoped_props;
+
+	ZEND_PARSE_PARAMETERS_START(2, 2)
+		Z_PARAM_ZVAL(object_or_class)
+		Z_PARAM_ARRAY_HT(scoped_props)
+	ZEND_PARSE_PARAMETERS_END();
+
+	zval obj_zval;
+	bool created = false;
+
+	if (Z_TYPE_P(object_or_class) == IS_OBJECT) {
+		ZVAL_COPY(&obj_zval, object_or_class);
+	} else if (Z_TYPE_P(object_or_class) == IS_STRING) {
+		zend_class_entry *ce = zend_lookup_class(Z_STR_P(object_or_class));
+		if (!ce) {
+			zend_throw_exception_ex(dc_ce_class_not_found_exception, 0,
+				"Class \"%s\" not found.", Z_STRVAL_P(object_or_class));
+			return;
+		}
+		if (UNEXPECTED(object_init_ex(&obj_zval, ce) != SUCCESS)) {
+			return;
+		}
+		created = true;
+	} else {
+		zend_type_error("deepclone_hydrate(): Argument #1 ($objectOrClass) must be of type object|string, %s given",
+			zend_zval_value_name(object_or_class));
+		return;
+	}
+
+	zend_string *scope_name;
+	zval *scope_props;
+	ZEND_HASH_FOREACH_STR_KEY_VAL(scoped_props, scope_name, scope_props) {
+		if (!scope_name || Z_TYPE_P(scope_props) != IS_ARRAY) {
+			continue;
+		}
+
+		zend_class_entry *scope_ce = NULL;
+		if (!zend_string_equals(scope_name, ZEND_STANDARD_CLASS_DEF_PTR->name)) {
+			scope_ce = zend_lookup_class(scope_name);
+		}
+
+#if PHP_VERSION_ID >= 80500
+		const zend_class_entry *old_scope = EG(fake_scope);
+#else
+		zend_class_entry *old_scope = EG(fake_scope);
+#endif
+		if (scope_ce) {
+			EG(fake_scope) = scope_ce;
+		}
+
+		zend_object *obj = Z_OBJ(obj_zval);
+		zend_string *prop_name;
+		zval *prop_val;
+		ZEND_HASH_FOREACH_STR_KEY_VAL(Z_ARRVAL_P(scope_props), prop_name, prop_val) {
+			if (!prop_name) continue;
+
+			if (obj->ce == zend_standard_class_def) {
+				if (UNEXPECTED(!obj->properties)) {
+					rebuild_object_properties_internal(obj);
+				}
+				Z_TRY_ADDREF_P(prop_val);
+				zend_hash_update(obj->properties, prop_name, prop_val);
+			} else {
+				zend_std_write_property(obj, prop_name, prop_val, NULL);
+				if (UNEXPECTED(EG(exception))) {
+					EG(fake_scope) = old_scope;
+					if (created) {
+						zval_ptr_dtor(&obj_zval);
+					}
+					return;
+				}
+			}
+		} ZEND_HASH_FOREACH_END();
+
+		EG(fake_scope) = old_scope;
+	} ZEND_HASH_FOREACH_END();
+
+	ZVAL_COPY_VALUE(return_value, &obj_zval);
+}
+
 /* ── Module boilerplate ─────────────────────────────────────── */
 
 /* Function arginfo and ext_functions[] are generated from deepclone.stub.php

deepclone.stub.php

@@ -14,4 +14,6 @@ class ClassNotFoundException extends \InvalidArgumentException {}
     function deepclone_to_array(mixed $value, ?array $allowedClasses = null): array {}
 
     function deepclone_from_array(array $data, ?array $allowedClasses = null): mixed {}
+
+    function deepclone_hydrate(object|string $objectOrClass, array $scopedProperties): object {}
 }

deepclone_arginfo.h

@@ -1,5 +1,4 @@
-/* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 571596a6888d66145a5b0d1b8391a4fa7d88506d */
+/* This is a generated file, edit the .stub.php file instead. */
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_deepclone_to_array, 0, 1, IS_ARRAY, 0)
 	ZEND_ARG_TYPE_INFO(0, value, IS_MIXED, 0)
@@ -11,12 +10,19 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_deepclone_from_array, 0, 1, IS_M
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, allowedClasses, IS_ARRAY, 1, "null")
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_deepclone_hydrate, 0, 2, IS_OBJECT, 0)
+	ZEND_ARG_TYPE_MASK(0, objectOrClass, MAY_BE_OBJECT|MAY_BE_STRING, NULL)
+	ZEND_ARG_TYPE_INFO(0, scopedProperties, IS_ARRAY, 0)
+ZEND_END_ARG_INFO()
+
 ZEND_FUNCTION(deepclone_to_array);
 ZEND_FUNCTION(deepclone_from_array);
+ZEND_FUNCTION(deepclone_hydrate);
 
 static const zend_function_entry ext_functions[] = {
 	ZEND_FE(deepclone_to_array, arginfo_deepclone_to_array)
 	ZEND_FE(deepclone_from_array, arginfo_deepclone_from_array)
+	ZEND_FE(deepclone_hydrate, arginfo_deepclone_hydrate)
 	ZEND_FE_END
 };
 

tests/deepclone_hydrate.phpt

@@ -0,0 +1,75 @@
+--TEST--
+deepclone_hydrate() instantiates and hydrates objects with scoped properties
+--EXTENSIONS--
+deepclone
+--FILE--
+<?php
+
+class Base {
+    private string $secret = '';
+    public function getSecret(): string { return $this->secret; }
+}
+
+class Child extends Base {
+    protected int $num = 0;
+    public string $pub = '';
+    public function getNum(): int { return $this->num; }
+}
+
+// Instantiate from class name
+$obj = deepclone_hydrate('Child', [
+    'Base' => ['secret' => 'hidden'],
+    'Child' => ['num' => 42],
+    'stdClass' => ['pub' => 'visible'],
+]);
+var_dump($obj instanceof Child);
+var_dump($obj->getSecret() === 'hidden');
+var_dump($obj->getNum() === 42);
+var_dump($obj->pub === 'visible');
+
+// Hydrate existing object
+$existing = new Child();
+$result = deepclone_hydrate($existing, [
+    'Base' => ['secret' => 'updated'],
+    'stdClass' => ['pub' => 'changed'],
+]);
+var_dump($result === $existing);
+var_dump($result->getSecret() === 'updated');
+var_dump($result->pub === 'changed');
+var_dump($result->getNum() === 0); // untouched
+
+// stdClass
+$o = deepclone_hydrate('stdClass', ['stdClass' => ['x' => 1, 'y' => 'hi']]);
+var_dump($o->x === 1);
+var_dump($o->y === 'hi');
+
+// Error: unknown class
+try {
+    deepclone_hydrate('NoSuchClass99', []);
+} catch (\DeepClone\ClassNotFoundException $e) {
+    var_dump(str_contains($e->getMessage(), 'NoSuchClass99'));
+}
+
+// Error: bad type
+try {
+    deepclone_hydrate(123, []);
+} catch (\TypeError $e) {
+    var_dump(str_contains($e->getMessage(), 'must be of type object|string'));
+}
+
+echo "Done\n";
+?>
+--EXPECT--
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+bool(true)
+Done