Add lazy and proxy helpers

Author: timacdonald

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,60 @@ 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 $supported = version_compare(phpversion(), '8.4.0', '>=');
+
+        if (! $supported) {
+            throw new RuntimeException('The `lazy` helper is only supported in PHP 8.4 or higher.');
+        }
+
+        static $closureReflector = null;
+
+        $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 +350,45 @@ 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
+     * @return TValue
+     */
+    function proxy($class, $callback = 0, $options = 0)
+    {
+        static $supported = version_compare(phpversion(), '8.4.0', '>=');
+
+        if (! $supported) {
+            throw new RuntimeException('The `lazy` helper is only supported in PHP 8.4 or higher.');
+        }
+
+        static $clousreReflector = null;
+
+       $clousreReflector ??= new class
+        {
+            use ReflectsClosures;
+
+            public function typeFromParameter($callback)
+            {
+                return $this->firstClosureParameterType($callback);
+            }
+        };
+
+        [$class, $callback, $options] = is_string($class)
+            ? [$class, $callback, $options]
+            : [$clousreReflector->typeFromParameter($class), $class, $callback ?: $options];
+
+        return (new ReflectionClass($class))->newLazyProxy($callback, $options);
+    }
+}
+
 if (! function_exists('retry')) {
     /**
      * Retry an operation a given number of times.