Lazy Objects helper (#64)

* lazy helper

* compatibility check

* comments

* fixes

* without tagging

* test

* test

* only proxy

* lazy variants

* lazy variants

* lazy variants

* Update src/Container.php

Co-authored-by: Harald Leithner <leithner@itronic.at>

* lazy variants

* lazy variants final

* lazy variants final

* lazy variants test

---------

Co-authored-by: Harald Leithner <leithner@itronic.at>

Author: Fedik

Tests/ContainerSetupTest.php

@@ -318,4 +318,46 @@ static function () {
 
         $container->get('foo');
     }
+
+    /**
+     * @testdox  Create Lazy Proxy
+     *
+     * @covers   Joomla\DI\Container
+     */
+    public function testCreateLazyProxy()
+    {
+        $container = new Container();
+        $container->lazy(Stub6::class, function () {
+            return new Stub6();
+        });
+
+        $resource = $container->get(Stub6::class);
+
+        $this->assertTrue($resource instanceof Stub6);
+    }
+
+    /**
+     * @testdox  If the resource is created with a proxy class
+     *
+     * @uses     Joomla\DI\Container
+     */
+    public function testGetLazyProxyInstance()
+    {
+        if (PHP_VERSION_ID < 80400) {
+            $this->markTestSkipped('Lazy objects are only supported in PHP 8.4 or newer.');
+        }
+
+        $factoryCalled = false;
+
+        $container = new Container();
+        $container->lazy(Stub6::class, function () use (&$factoryCalled) {
+            $factoryCalled = true;
+            return new Stub6();
+        });
+
+        $resource = $container->get(Stub6::class);
+
+        $this->assertTrue((new \ReflectionClass(Stub6::class))->isUninitializedLazyObject($resource));
+        $this->assertFalse($factoryCalled);
+    }
 }

src/Container.php

@@ -665,6 +665,34 @@ public function share($key, $value, $protected = false)
         return $this->set($key, $value, true, $protected);
     }
 
+    /**
+     * Create a lazy proxy resource for given class, and register it in the Container.
+     *
+     * @param   string         $class      Full class name of the resource.
+     * @param   callable       $factory    Callback to create the class instance. The callback must return instance of the given class.
+     * @param   boolean        $shared     True to create and store a shared instance.
+     * @param   boolean        $protected  True to protect this item from being overwritten. Useful for services.
+     *
+     * @return  $this
+     *
+     * @since   __DEPLOY_VERSION__
+     */
+    final public function lazy(string $class, callable $factory, bool $shared = false, bool $protected = false): static
+    {
+        if (PHP_VERSION_ID < 80400) {
+            return $this->set($class, $factory, $shared, $protected);
+        }
+
+        // Create a Lazy Proxy factory
+        $lazyFactory = function () use ($class, $factory) {
+            return (new \ReflectionClass($class))->newLazyProxy(function () use ($factory) {
+                return $factory($this);
+            });
+        };
+
+        return $this->set($class, $lazyFactory, $shared, $protected);
+    }
+
     /**
      * Get the raw data assigned to a key.
      *