feat(container): support lazy dependency initialization using lazy proxies (#1090)

Co-authored-by: Brent Roose <[email protected]>

Author: SamMousa

src/Tempest/Container/src/GenericContainer.php

@@ -353,7 +353,13 @@ private function autowire(string $className, mixed ...$params): object
 
         foreach ($classReflector->getProperties() as $property) {
             if ($property->hasAttribute(Inject::class) && ! $property->isInitialized($instance)) {
-                $property->set($instance, $this->get($property->getType()->getName()));
+                if ($property->hasAttribute(Lazy::class)) {
+                    $property->set($instance, $property->getType()->asClass()->getReflection()->newLazyProxy(
+                        fn () => $this->get($property->getType()->getName()),
+                    ));
+                } else {
+                    $property->set($instance, $this->get($property->getType()->getName()));
+                }
             }
         }
 
@@ -392,13 +398,16 @@ private function autowireDependency(ParameterReflector $parameter, ?string $tag,
             return $this->autowireBuiltinDependency($parameter, $providedValue);
         }
 
+        // Support lazy initialization
+        $lazy = $parameter->hasAttribute(Lazy::class);
         // Loop through each type until we hit a match.
         foreach ($parameter->getType()->split() as $type) {
             try {
                 return $this->autowireObjectDependency(
                     type: $type,
                     tag: $tag,
                     providedValue: $providedValue,
+                    lazy: $lazy,
                 );
             } catch (Throwable $throwable) {
                 // We were unable to resolve the dependency for the last union
@@ -419,14 +428,23 @@ private function autowireDependency(ParameterReflector $parameter, ?string $tag,
         throw $lastThrowable ?? new CannotAutowireException($this->chain, new Dependency($parameter));
     }
 
-    private function autowireObjectDependency(TypeReflector $type, ?string $tag, mixed $providedValue): mixed
+    private function autowireObjectDependency(TypeReflector $type, ?string $tag, mixed $providedValue, bool $lazy): mixed
     {
         // If the provided value is of the right type,
         // don't waste time autowiring, return it!
         if ($type->accepts($providedValue)) {
             return $providedValue;
         }
 
+        if ($lazy) {
+            return $type
+                ->asClass()
+                ->getReflection()
+                ->newLazyProxy(function () use ($type, $tag) {
+                    return $this->resolve(className: $type->getName(), tag: $tag);
+                });
+        }
+
         // If we can successfully retrieve an instance
         // of the necessary dependency, return it.
         return $this->resolve(className: $type->getName(), tag: $tag);

src/Tempest/Container/src/Lazy.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\Container;
+
+use Attribute;
+
+/**
+ * Add this to an attribute that has #[Inject] or a constructor parameter to indicate
+ * that your class might not always use this dependency.
+ * The container may then decide to do lazy initialization
+ */
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_PARAMETER)]
+final readonly class Lazy
+{
+}

src/Tempest/Container/tests/ContainerTest.php

@@ -20,7 +20,10 @@
 use Tempest\Container\Tests\Fixtures\CallContainerObjectE;
 use Tempest\Container\Tests\Fixtures\CircularWithInitializerA;
 use Tempest\Container\Tests\Fixtures\CircularWithInitializerBInitializer;
+use Tempest\Container\Tests\Fixtures\ClassWithLazySlowDependency;
+use Tempest\Container\Tests\Fixtures\ClassWithLazySlowPropertyDependency;
 use Tempest\Container\Tests\Fixtures\ClassWithSingletonAttribute;
+use Tempest\Container\Tests\Fixtures\ClassWithSlowDependency;
 use Tempest\Container\Tests\Fixtures\ContainerObjectA;
 use Tempest\Container\Tests\Fixtures\ContainerObjectB;
 use Tempest\Container\Tests\Fixtures\ContainerObjectC;
@@ -41,6 +44,7 @@
 use Tempest\Container\Tests\Fixtures\OptionalTypesClass;
 use Tempest\Container\Tests\Fixtures\SingletonClass;
 use Tempest\Container\Tests\Fixtures\SingletonInitializer;
+use Tempest\Container\Tests\Fixtures\SlowDependency;
 use Tempest\Container\Tests\Fixtures\TaggedDependency;
 use Tempest\Container\Tests\Fixtures\TaggedDependencyCliInitializer;
 use Tempest\Container\Tests\Fixtures\TaggedDependencyWebInitializer;
@@ -474,4 +478,83 @@ public function test_has_tagged_singleton(): void
 
         $this->assertTrue($container->has(TaggedDependency::class, 'web'));
     }
+
+    /**
+     * @template T
+     * @param (callable(): T) $callable
+     * @return T
+     */
+    private function assertFasterThan(callable $callable, float $seconds): mixed
+    {
+        $start = microtime(true);
+        $result = $callable();
+        $end = microtime(true);
+        $this->assertLessThan($seconds, $end - $start);
+        return $result;
+    }
+
+    /**
+     * @template T
+     * @param (callable(): T) $callable
+     * @return T
+     */
+    private function assertSlowerThan(callable $callable, float $seconds): mixed
+    {
+        $start = microtime(true);
+        $result = $callable();
+        $end = microtime(true);
+        $this->assertGreaterThan($seconds, $end - $start);
+        return $result;
+    }
+
+    public function test_lazy_dependency(): void
+    {
+        $container = new GenericContainer();
+
+        /**
+         * Set the load time of the dependency, increasing this increases test time but makes the test more robust
+         * At extremely low values other operations might have a bigger effect than the usleep inside the slow dependency
+         */
+        $delay = 0.01;
+        $counter = 1;
+
+        $container->register(SlowDependency::class, function () use ($delay, &$counter) {
+            return new SlowDependency($delay, $counter++);
+        });
+
+        // Normal example, this is slow during initialization, fast during use
+        $instance1 = $this->assertSlowerThan(fn () => $container->get(ClassWithSlowDependency::class), $delay);
+        $this->assertInstanceOf(ClassWithSlowDependency::class, $instance1);
+        $this->assertInstanceOf(SlowDependency::class, $instance1->dependency);
+
+        $this->assertSame('value1', $this->assertFasterThan(fn () => $instance1->dependency->value, $delay));
+
+        // Lazy example, this is fast during initialization, slow during (first) use
+        $instance2 = $this->assertFasterThan(fn () => $container->get(ClassWithLazySlowDependency::class), $delay);
+        $this->assertInstanceOf(ClassWithLazySlowDependency::class, $instance2);
+        $this->assertInstanceOf(SlowDependency::class, $instance2->dependency);
+
+        $this->assertSame('value2', $this->assertSlowerThan(fn () => $instance2->dependency->value, $delay));
+    }
+
+    public function test_lazy_property_dependency(): void
+    {
+        $container = new GenericContainer();
+
+        /**
+         * Set the load time of the dependency, increasing this increases test time but makes the test more robust
+         * At extremely low values other operations might have a bigger effect than the usleep inside the slow dependency
+         */
+        $delay = 0.01;
+        $counter = 1;
+
+        $container->register(SlowDependency::class, function () use ($delay, &$counter) {
+            return new SlowDependency($delay, $counter++);
+        });
+
+        $instance = $this->assertFasterThan(fn () => $container->get(ClassWithLazySlowPropertyDependency::class), $delay);
+        $this->assertInstanceOf(SlowDependency::class, $instance->dependency);
+
+        $this->assertSame('value1', $this->assertSlowerThan(fn () => $instance->dependency->value, $delay));
+    }
 }

src/Tempest/Container/tests/Fixtures/ClassWithLazySlowDependency.php

@@ -0,0 +1,14 @@
+<?php
+declare(strict_types=1);
+
+namespace Tempest\Container\Tests\Fixtures;
+
+use Tempest\Container\Lazy;
+
+final readonly class ClassWithLazySlowDependency
+{
+    public function __construct(
+        #[Lazy]
+        public SlowDependency $dependency,
+    ) {}
+}

src/Tempest/Container/tests/Fixtures/ClassWithLazySlowPropertyDependency.php

@@ -0,0 +1,16 @@
+<?php
+declare(strict_types=1);
+
+namespace Tempest\Container\Tests\Fixtures;
+
+use Tempest\Container\Inject;
+use Tempest\Container\Lazy;
+
+final class ClassWithLazySlowPropertyDependency
+{
+    #[Inject]
+    #[Lazy]
+    private(set) SlowDependency $dependency;
+
+    public function __construct() {}
+}

src/Tempest/Container/tests/Fixtures/ClassWithSlowDependency.php

@@ -0,0 +1,11 @@
+<?php
+declare(strict_types=1);
+
+namespace Tempest\Container\Tests\Fixtures;
+
+final readonly class ClassWithSlowDependency
+{
+    public function __construct(
+        public SlowDependency $dependency,
+    ) {}
+}

src/Tempest/Container/tests/Fixtures/SlowDependency.php

@@ -0,0 +1,20 @@
+<?php
+declare(strict_types=1);
+
+namespace Tempest\Container\Tests\Fixtures;
+
+final readonly class SlowDependency
+{
+    public string $value;
+
+    public function __construct(float $delay = 0.1, $counter = 0)
+    {
+        // usleep apparently is buggy on windows...
+        $start = microtime(true);
+        while ((microtime(true) - $start) < $delay) {
+            usleep(intval($delay * 1000000));
+        }
+
+        $this->value = 'value' . $counter;
+    }
+}

src/Tempest/Reflection/src/HasAttributes.php

@@ -14,6 +14,9 @@ trait HasAttributes
 {
     abstract public function getReflection(): PHPReflectionClass|PHPReflectionMethod|PHPReflectionProperty|PHPReflectionParameter;
 
+    /**
+     * @param class-string $name
+     */
     public function hasAttribute(string $name): bool
     {
         return $this->getReflection()->getAttributes($name) !== [];