Introduce lazy object and proxy object support helpers (#57831)

* Add lazy and proxy helpers

* Use factories in tests to better reflect usage

* Improve test names

* Pass eager properties through to proxy method

* Remove version compare

* Extract return type reflector to trait

* Add return type closure detection

Author: timacdonald

src/Illuminate/Container/Container.php

@@ -14,6 +14,7 @@
 use Illuminate\Contracts\Container\ContextualAttribute;
 use Illuminate\Contracts\Container\SelfBuilding;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Traits\ReflectsClosures;
 use LogicException;
 use ReflectionAttribute;
 use ReflectionClass;
@@ -26,6 +27,8 @@
 
 class Container implements ArrayAccess, ContainerContract
 {
+    use ReflectsClosures;
+
     /**
      * The current globally available container (if any).
      *
@@ -568,35 +571,6 @@ protected function bindBasedOnClosureReturnTypes($abstract, $concrete = null, $s
         }
     }
 
-    /**
-     * Get the class names / types of the return type of the given Closure.
-     *
-     * @param  \Closure  $closure
-     * @return list<class-string>
-     *
-     * @throws \ReflectionException
-     */
-    protected function closureReturnTypes(Closure $closure)
-    {
-        $reflection = new ReflectionFunction($closure);
-
-        if ($reflection->getReturnType() === null ||
-            $reflection->getReturnType() instanceof ReflectionIntersectionType) {
-            return [];
-        }
-
-        $types = $reflection->getReturnType() instanceof ReflectionUnionType
-            ? $reflection->getReturnType()->getTypes()
-            : [$reflection->getReturnType()];
-
-        return (new Collection($types))
-            ->reject(fn ($type) => $type->isBuiltin())
-            ->reject(fn ($type) => in_array($type->getName(), ['static', 'self']))
-            ->map(fn ($type) => $type->getName())
-            ->values()
-            ->all();
-    }
-
     /**
      * "Extend" an abstract type in the container.
      *

src/Illuminate/Support/Traits/ReflectsClosures.php

@@ -6,6 +6,8 @@
 use Illuminate\Support\Collection;
 use Illuminate\Support\Reflector;
 use ReflectionFunction;
+use ReflectionIntersectionType;
+use ReflectionUnionType;
 use RuntimeException;
 
 trait ReflectsClosures
@@ -92,4 +94,33 @@ protected function closureParameterTypes(Closure $closure)
             })
             ->all();
     }
+
+    /**
+     * Get the class names / types of the return type of the given Closure.
+     *
+     * @param  \Closure  $closure
+     * @return list<class-string>
+     *
+     * @throws \ReflectionException
+     */
+    protected function closureReturnTypes(Closure $closure)
+    {
+        $reflection = new ReflectionFunction($closure);
+
+        if ($reflection->getReturnType() === null ||
+            $reflection->getReturnType() instanceof ReflectionIntersectionType) {
+            return [];
+        }
+
+        $types = $reflection->getReturnType() instanceof ReflectionUnionType
+            ? $reflection->getReturnType()->getTypes()
+            : [$reflection->getReturnType()];
+
+        return (new Collection($types))
+            ->reject(fn ($type) => $type->isBuiltin())
+            ->reject(fn ($type) => in_array($type->getName(), ['static', 'self']))
+            ->map(fn ($type) => $type->getName())
+            ->values()
+            ->all();
+    }
 }

src/Illuminate/Support/helpers.php

@@ -13,6 +13,7 @@
 use Illuminate\Support\Sleep;
 use Illuminate\Support\Str;
 use Illuminate\Support\Stringable as SupportStringable;
+use Illuminate\Support\Traits\ReflectsClosures;
 
 if (! function_exists('append_config')) {
     /**
@@ -196,6 +197,54 @@ function literal(...$arguments)
     }
 }
 
+if (! function_exists('lazy')) {
+    /**
+     * Create a lazy instance.
+     *
+     * @template TValue of object
+     *
+     * @param  class-string<TValue>|(\Closure(TValue): mixed)  $class
+     * @param  (\Closure(TValue): mixed)|int  $callback
+     * @param  int  $options
+     * @param  array<string, mixed>  $eager
+     * @return TValue
+     */
+    function lazy($class, $callback = 0, $options = 0, $eager = [])
+    {
+        static $closureReflector;
+
+        $closureReflector ??= new class
+        {
+            use ReflectsClosures;
+
+            public function typeFromParameter($callback)
+            {
+                return $this->firstClosureParameterType($callback);
+            }
+        };
+
+        [$class, $callback, $options] = is_string($class)
+            ? [$class, $callback, $options]
+            : [$closureReflector->typeFromParameter($class), $class, $callback ?: $options];
+
+        $reflectionClass = new ReflectionClass($class);
+
+        $instance = $reflectionClass->newLazyGhost(function ($instance) use ($callback) {
+            $result = $callback($instance);
+
+            if (is_array($result)) {
+                $instance->__construct(...$result);
+            }
+        }, $options);
+
+        foreach ($eager as $property => $value) {
+            $reflectionClass->getProperty($property)->setRawValueWithoutLazyInitialization($instance, $value);
+        }
+
+        return $instance;
+    }
+}
+
 if (! function_exists('object_get')) {
     /**
      * Get an item from an object using "dot" notation.
@@ -295,6 +344,52 @@ function preg_replace_array($pattern, array $replacements, $subject): string
     }
 }
 
+if (! function_exists('proxy')) {
+    /**
+     * Create a lazy proxy instance.
+     *
+     * @template TValue of object
+     *
+     * @param  class-string<TValue>|(\Closure(TValue): TValue)  $class
+     * @param  (\Closure(TValue): TValue)|int  $callback
+     * @param  int  $options
+     * @param  array<string, mixed>  $eager
+     * @return TValue
+     */
+    function proxy($class, $callback = 0, $options = 0, $eager = [])
+    {
+        static $closureReflector;
+
+        $closureReflector = new class
+        {
+            use ReflectsClosures;
+
+            public function get($callback)
+            {
+                return $this->closureReturnTypes($callback)[0] ?? $this->firstClosureParameterType($callback);
+            }
+        };
+
+        [$class, $callback, $options] = is_string($class)
+            ? [$class, $callback, $options]
+            : [$closureReflector->get($class), $class, $callback ?: $options];
+
+        $reflectionClass = new ReflectionClass($class);
+
+        $proxy = $reflectionClass->newLazyProxy(function () use ($callback, $eager, &$proxy) {
+            $instance = $callback($proxy, $eager);
+
+            return $instance;
+        }, $options);
+
+        foreach ($eager as $property => $value) {
+            $reflectionClass->getProperty($property)->setRawValueWithoutLazyInitialization($proxy, $value);
+        }
+
+        return $proxy;
+    }
+}
+
 if (! function_exists('retry')) {
     /**
      * Retry an operation a given number of times.