[DeepClone] Add deepclone_hydrate() polyfill

nicolas-grekas · nicolas-grekas · commit 831ba126b8bd · 2026-04-11T22:59:30.000+02:00
Add pure-PHP implementation of deepclone_hydrate(object|string, array $properties, array $scopedProperties): object Matches the C extension (symfony/php-ext-deepclone#6): - Flat $properties with mangled key format ("\0Class\0prop", "\0*\0prop") - Pre-scoped $scopedProperties keyed by declaring class - SPL special "\0" key for ArrayObject, ArrayIterator, SplObjectStorage - PHP & reference preservation - Instantiability validation via getClassReflector() - ValueError on integer keys or non-array scoped values - Enum rejection in getClassReflector()
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,7 @@
+# 1.35.0
+
+  * Add polyfill for `deepclone_hydrate()`
+
 # 1.34.0
 
   * Add polyfill for the `symfony/deepclone` extension
diff --git a/src/DeepClone/DeepClone.php b/src/DeepClone/DeepClone.php
@@ -33,6 +33,7 @@ final class DeepClone
     private static array $instantiableWithoutConstructor = [];
     private static array $needsFullUnserialize = [];
     private static array $hydrators = [];
+    private static array $simpleHydrators = [];
     private static array $scopeMaps = [];
     private static array $protos = [];
     private static array $classInfo = [];
@@ -1002,7 +1003,7 @@ private static function getClassReflector($class, $instantiableWithoutConstructo
 
         if ($instantiableWithoutConstructor) {
             $proto = $reflector->newInstanceWithoutConstructor();
-        } elseif (!$isClass || $reflector->isAbstract()) {
+        } elseif (!$isClass || $reflector->isAbstract() || $reflector->isEnum()) {
             throw new \DeepClone\NotInstantiableException('Type "'.$class.'" is not instantiable.');
         } elseif ($reflector->name !== $class) {
             $reflector = self::$reflectors[$name = $reflector->name] ??= self::getClassReflector($name, false, $cloneable);
@@ -1183,6 +1184,202 @@ private static function getHydrator($class)
             }
         };
     }
+
+    public static function deepclone_hydrate(object|string $objectOrClass, array $properties = [], array $scopedProperties = []): object
+    {
+        if (\is_string($objectOrClass)) {
+            if (!\array_key_exists($objectOrClass, self::$cloneable)) {
+                self::getClassReflector($objectOrClass);
+            }
+            $r = self::$reflectors[$objectOrClass] ?? new \ReflectionClass($objectOrClass);
+            if (self::$cloneable[$objectOrClass]) {
+                $object = clone self::$prototypes[$objectOrClass];
+            } elseif (self::$instantiableWithoutConstructor[$objectOrClass]) {
+                $object = $r->newInstanceWithoutConstructor();
+            } elseif (null === self::$prototypes[$objectOrClass]) {
+                throw new \DeepClone\NotInstantiableException('Class "'.$objectOrClass.'" is not instantiable.');
+            } elseif ($r->implementsInterface('Serializable') && !method_exists($objectOrClass, '__unserialize')) {
+                $object = unserialize('C:'.\strlen($objectOrClass).':"'.$objectOrClass.'":0:{}');
+            } else {
+                $object = unserialize('O:'.\strlen($objectOrClass).':"'.$objectOrClass.'":0:{}');
+            }
+        } else {
+            $object = $objectOrClass;
+        }
+
+        if ($properties) {
+            $class = $object::class;
+            $r ??= new \ReflectionClass($class);
+
+            foreach ($properties as $name => &$value) {
+                if (!\is_string($name)) {
+                    throw new \ValueError('deepclone_hydrate(): Argument #2 ($properties) must have only string keys');
+                }
+                if ("\0" === $name) {
+                    $scopedProperties[$class][$name] = &$value;
+                    continue;
+                }
+                if (\str_starts_with($name, "\0")) {
+                    $sep = \strpos($name, "\0", 1);
+                    if (false === $sep) {
+                        continue;
+                    }
+                    $scopeName = \substr($name, 1, $sep - 1);
+                    $realName = \substr($name, $sep + 1);
+
+                    if ('*' === $scopeName) {
+                        $scopeName = $r->hasProperty($realName) ? $r->getProperty($realName)->class : $class;
+                    }
+                } else {
+                    $realName = $name;
+                    $scopeName = $r->hasProperty($name) ? $r->getProperty($name)->class : $class;
+                }
+
+                $scopedProperties[$scopeName][$realName] = &$value;
+            }
+            unset($value);
+        }
+
+        foreach ($scopedProperties as $scope => $properties) {
+            if (!\is_array($properties)) {
+                throw new \ValueError(\sprintf('deepclone_hydrate(): Argument #3 ($scopedProperties) must have only array values, %s given for key "%s"', get_debug_type($properties), $scope));
+            }
+            if (isset($properties["\0"]) && \is_array($properties["\0"])) {
+                $special = $properties["\0"];
+                unset($properties["\0"]);
+
+                if ($object instanceof \SplObjectStorage) {
+                    for ($i = 0, $c = \count($special); $i + 1 < $c; $i += 2) {
+                        $object[$special[$i]] = $special[$i + 1];
+                    }
+                } elseif ($object instanceof \ArrayObject || $object instanceof \ArrayIterator) {
+                    (new \ReflectionClass($object))->getConstructor()->invokeArgs($object, $special);
+                }
+            }
+            if ($properties) {
+                (self::$simpleHydrators[$scope] ??= self::getSimpleHydrator($scope))($properties, $object);
+            }
+        }
+
+        return $object;
+    }
+
+    private static function getSimpleHydrator(string $class): \Closure
+    {
+        $baseHydrator = self::$simpleHydrators['stdClass'] ??= static function ($properties, $object) {
+            foreach ($properties as $name => &$value) {
+                $object->$name = $value;
+                $object->$name = &$value;
+            }
+        };
+
+        switch ($class) {
+            case 'stdClass':
+                return $baseHydrator;
+
+            case 'TypeError':
+                $class = 'Error';
+                break;
+
+            case 'ErrorException':
+                $class = 'Exception';
+                break;
+
+            case 'SplObjectStorage':
+                return static function ($properties, $object) {
+                    foreach ($properties as $name => &$value) {
+                        if ("\0" !== $name) {
+                            $object->$name = $value;
+                            $object->$name = &$value;
+                            continue;
+                        }
+                        for ($i = 0; $i < \count($value); ++$i) {
+                            $object[$value[$i]] = $value[++$i];
+                        }
+                    }
+                };
+        }
+
+        if (!class_exists($class) && !interface_exists($class, false) && !trait_exists($class, false)) {
+            throw new \DeepClone\ClassNotFoundException('Class "'.$class.'" not found.');
+        }
+        $classReflector = new \ReflectionClass($class);
+
+        switch ($class) {
+            case 'ArrayIterator':
+            case 'ArrayObject':
+                $constructor = $classReflector->getConstructor()->invokeArgs(...);
+
+                return static function ($properties, $object) use ($constructor) {
+                    foreach ($properties as $name => &$value) {
+                        if ("\0" === $name) {
+                            $constructor($object, $value);
+                        } else {
+                            $object->$name = $value;
+                            $object->$name = &$value;
+                        }
+                    }
+                };
+        }
+
+        if (!$classReflector->isInternal()) {
+            $notByRef = new \stdClass();
+            foreach ($classReflector->getProperties() as $propertyReflector) {
+                if ($propertyReflector->isStatic()) {
+                    continue;
+                }
+                if (\PHP_VERSION_ID >= 80400 && !$propertyReflector->isAbstract() && $propertyReflector->getHooks()) {
+                    $notByRef->{$propertyReflector->name} = $propertyReflector->setRawValue(...);
+                } elseif ($propertyReflector->isReadOnly()) {
+                    $notByRef->{$propertyReflector->name} = static function ($object, $value) use ($propertyReflector) {
+                        if (!$propertyReflector->isInitialized($object)) {
+                            $propertyReflector->setValue($object, $value);
+                        }
+                    };
+                }
+            }
+
+            return (function ($properties, $object) {
+                $notByRef = (array) $this;
+
+                foreach ($properties as $name => &$value) {
+                    if (!$noRef = $notByRef[$name] ?? false) {
+                        $object->$name = $value;
+                        $object->$name = &$value;
+                    } elseif (true !== $noRef) {
+                        $noRef($object, $value);
+                    } else {
+                        $object->$name = $value;
+                    }
+                }
+            })->bindTo($notByRef, $class);
+        }
+
+        if ($classReflector->name !== $class) {
+            return self::$simpleHydrators[$classReflector->name] ??= self::getSimpleHydrator($classReflector->name);
+        }
+
+        $propertySetters = [];
+        foreach ($classReflector->getProperties() as $propertyReflector) {
+            if (!$propertyReflector->isStatic()) {
+                $propertySetters[$propertyReflector->name] = $propertyReflector->setValue(...);
+            }
+        }
+
+        if (!$propertySetters) {
+            return $baseHydrator;
+        }
+
+        return static function ($properties, $object) use ($propertySetters) {
+            foreach ($properties as $name => $value) {
+                if ($setValue = $propertySetters[$name] ?? null) {
+                    $setValue($object, $value);
+                    continue;
+                }
+                $object->$name = $value;
+            }
+        };
+    }
 }
 
 /**
diff --git a/src/DeepClone/bootstrap.php b/src/DeepClone/bootstrap.php
@@ -15,9 +15,6 @@
     return;
 }
 
-if (!function_exists('deepclone_to_array')) {
-    function deepclone_to_array(mixed $value, ?array $allowedClasses = null): array { return p\DeepClone::deepclone_to_array($value, $allowedClasses); }
-}
-if (!function_exists('deepclone_from_array')) {
-    function deepclone_from_array(array $data, ?array $allowedClasses = null): mixed { return p\DeepClone::deepclone_from_array($data, $allowedClasses); }
+if (\PHP_VERSION_ID >= 80200) {
+    require ___DIR__.'/bootstrap82.php;
 }
diff --git a/src/DeepClone/bootstrap82.php b/src/DeepClone/bootstrap82.php
@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\Polyfill\DeepClone as p;
+
+if (extension_loaded('deepclone')) {
+    return;
+}
+
+if (!function_exists('deepclone_to_array')) {
+    function deepclone_to_array(mixed $value, ?array $allowedClasses = null): array { return p\DeepClone::deepclone_to_array($value, $allowedClasses); }
+}
+if (!function_exists('deepclone_from_array')) {
+    function deepclone_from_array(array $data, ?array $allowedClasses = null): mixed { return p\DeepClone::deepclone_from_array($data, $allowedClasses); }
+}
+if (!function_exists('deepclone_hydrate')) {
+    function deepclone_hydrate(object|string $objectOrClass, array $properties = [], array $scopedProperties = []): object { return p\DeepClone::deepclone_hydrate($objectOrClass, $properties, $scopedProperties); }
+}
diff --git a/tests/DeepClone/DeepCloneTest.php b/tests/DeepClone/DeepCloneTest.php
diff --git a/tests/DeepClone/fixtures.php b/tests/DeepClone/fixtures.php

Original file line number	Diff line number	Diff line change
`@@ -15,9 +15,6 @@`
`15`	`15`	`return;`
`16`	`16`	`}`
`17`	`17`
`18`		`-if (!function_exists('deepclone_to_array')) {`
`19`		`- function deepclone_to_array(mixed $value, ?array $allowedClasses = null): array { return p\DeepClone::deepclone_to_array($value, $allowedClasses); }`
`20`		`-}`
`21`		`-if (!function_exists('deepclone_from_array')) {`
`22`		`- function deepclone_from_array(array $data, ?array $allowedClasses = null): mixed { return p\DeepClone::deepclone_from_array($data, $allowedClasses); }`
	`18`	`+if (\PHP_VERSION_ID >= 80200) {`
	`19`	`+ require ___DIR__.'/bootstrap82.php;`
`23`	`20`	`}`