Lazy services

composer.json

@@ -25,11 +25,12 @@
         "php": "^8.0",
         "ext-mbstring": "*",
         "psr/container": "^1.1|^2.0",
-        "yiisoft/definitions": "^3.0"
+        "yiisoft/definitions": "dev-lazy-definition"
     },
     "require-dev": {
         "league/container": "^4.2",
         "maglnet/composer-require-checker": "^4.2",
+        "friendsofphp/proxy-manager-lts": "^1.0",
         "phpbench/phpbench": "^1.2.0",
         "phpunit/phpunit": "^9.5",
         "rector/rector": "^0.17.0",
@@ -41,7 +42,8 @@
     },
     "suggest": {
         "yiisoft/injector": "^1.0",
-        "phpbench/phpbench": "To run benchmarks."
+        "phpbench/phpbench": "To run benchmarks.",
+        "friendsofphp/proxy-manager-lts": "Install this package if you want to use lazy loading."
     },
     "provide": {
         "psr/container-implementation": "1.0.0"

src/Container.php

@@ -10,11 +10,13 @@
 use Psr\Container\NotFoundExceptionInterface;
 use Throwable;
 use Yiisoft\Definitions\ArrayDefinition;
+use Yiisoft\Definitions\Contract\DefinitionInterface;
 use Yiisoft\Definitions\DefinitionStorage;
 use Yiisoft\Definitions\Exception\CircularReferenceException;
 use Yiisoft\Definitions\Exception\InvalidConfigException;
 use Yiisoft\Definitions\Exception\NotInstantiableException;
 use Yiisoft\Definitions\Helpers\DefinitionValidator;
+use Yiisoft\Definitions\LazyDefinition;
 use Yiisoft\Di\Helpers\DefinitionNormalizer;
 use Yiisoft\Di\Helpers\DefinitionParser;
 use Yiisoft\Di\Helpers\TagHelper;
@@ -35,7 +37,8 @@
 {
     private const META_TAGS = 'tags';
     private const META_RESET = 'reset';
-    private const ALLOWED_META = [self::META_TAGS, self::META_RESET];
+    private const META_LAZY = 'lazy';
+    private const ALLOWED_META = [self::META_TAGS, self::META_RESET, self::META_LAZY];
 
     /**
      * @var DefinitionStorage Storage of object definitions.
@@ -206,7 +209,7 @@
             $this->validateMeta($meta);
         }
         /**
-         * @psalm-var array{reset?:Closure,tags?:string[]} $meta
+         * @psalm-var array{reset?:Closure,lazy?:bool,tags?:string[]} $meta
          */
 
         if (isset($meta[self::META_TAGS])) {
@@ -215,6 +218,9 @@
         if (isset($meta[self::META_RESET])) {
             $this->setDefinitionResetter($id, $meta[self::META_RESET]);
         }
+        if (isset($meta[self::META_LAZY]) && $meta[self::META_LAZY] === true) {
+            $definition = $this->decorateLazy($id, $definition);
+        }
 
         unset($this->instances[$id]);
         $this->addDefinitionToStorage($id, $definition);
@@ -251,8 +257,6 @@
      * Each delegate must is a callable in format "function (ContainerInterface $container): ContainerInterface".
      * The container instance returned is used in case a service can not be found in primary container.
      *
-     * @param array $delegates
-     *
      * @throws InvalidConfigException
      */
     private function setDelegates(array $delegates): void
@@ -623,4 +627,27 @@
 
         return $providerInstance;
     }
+
+    private function decorateLazy(string $id, mixed $definition): DefinitionInterface
+    {
+        if (class_exists($id) || interface_exists($id)) {
+            $class = $id;
+        } elseif (is_array($definition) && array_key_exists(ArrayDefinition::CLASS_NAME, $definition)) {
+            $class = (string) $definition[ArrayDefinition::CLASS_NAME];
+        } else {
+            throw new InvalidConfigException(
+                sprintf(
+                    'Invalid definition: lazy services are only available with array definitions or references. Got type "%s" for definition ID: "%s"',
+                    get_debug_type($definition),
+                    $id,
+                )
+            );
+        }
+
+        /**
+         * @var class-string $class
+         */
+
+        return new LazyDefinition($definition, $class);
+    }
 }

tests/Unit/Helpers/DefinitionParserTest.php

@@ -17,21 +17,23 @@ public function testParseCallableDefinition(): void
         $definition = [
             'definition' => $fn,
             'tags' => ['one', 'two'],
+            'lazy' => true,
         ];
         [$definition, $meta] = DefinitionParser::parse($definition);
         $this->assertSame($fn, $definition);
-        $this->assertSame(['tags' => ['one', 'two']], $meta);
+        $this->assertSame(['tags' => ['one', 'two'], 'lazy' => true], $meta);
     }
 
     public function testParseArrayCallableDefinition(): void
     {
         $definition = [
             'definition' => [StaticFactory::class, 'create'],
             'tags' => ['one', 'two'],
+            'lazy' => true,
         ];
         [$definition, $meta] = DefinitionParser::parse($definition);
         $this->assertSame([StaticFactory::class, 'create'], $definition);
-        $this->assertSame(['tags' => ['one', 'two']], $meta);
+        $this->assertSame(['tags' => ['one', 'two'], 'lazy' => true], $meta);
     }
 
     public function testParseArrayDefinition(): void
@@ -40,6 +42,7 @@ public function testParseArrayDefinition(): void
             'class' => EngineMarkOne::class,
             '__construct()' => [42],
             'tags' => ['one', 'two'],
+            'lazy' => true,
         ];
         [$definition, $meta] = DefinitionParser::parse($definition);
         $this->assertSame([
@@ -48,6 +51,6 @@ public function testParseArrayDefinition(): void
             'methodsAndProperties' => [],
             DefinitionParser::IS_PREPARED_ARRAY_DEFINITION_DATA => true,
         ], $definition);
-        $this->assertSame(['tags' => ['one', 'two']], $meta);
+        $this->assertSame(['tags' => ['one', 'two'], 'lazy' => true], $meta);
     }
 }

tests/Unit/LazyServiceContainerTest.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Di\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+use ProxyManager\Factory\LazyLoadingValueHolderFactory;
+use ProxyManager\Proxy\LazyLoadingInterface;
+use Yiisoft\Di\Container;
+use Yiisoft\Di\ContainerConfig;
+use Yiisoft\Di\Tests\Support\EngineMarkOne;
+
+class LazyServiceContainerTest extends TestCase
+{
+    protected function setUp(): void
+    {
+        if (!class_exists(LazyLoadingValueHolderFactory::class)) {
+            $this->markTestSkipped(
+                'You should install `friendsofphp/proxy-manager-lts` if you want to use lazy services.'
+            );
+        }
+    }
+
+    public function testIsTheSameObject(): void
+    {
+        $class = EngineMarkOne::class;
+        $number = 55;
+
+        $config = ContainerConfig::create()
+            ->withDefinitions([
+                EngineMarkOne::class => [
+                    'class' => $class,
+                    'setNumber()' => [$number],
+                    'lazy' => true,
+                ],
+            ]);
+        $container = new Container($config);
+
+        /* @var EngineMarkOne $object */
+        $object = $container->get($class);
+
+        self::assertInstanceOf(LazyLoadingInterface::class, $object);
+        self::assertInstanceOf(EngineMarkOne::class, $object);
+        self::assertFalse($object->isProxyInitialized());
+        self::assertEquals($number, $object->getNumber());
+        self::assertTrue($object->isProxyInitialized());
+
+        /* @var EngineMarkOne $object */
+        $object = $container->get($class);
+
+        self::assertInstanceOf(LazyLoadingInterface::class, $object);
+        self::assertInstanceOf(EngineMarkOne::class, $object);
+        self::assertTrue($object->isProxyInitialized());
+    }
+
+    /**
+     * @dataProvider lazyDefinitionDataProvider
+     */
+    public function testLazy(array $definitions, string $id): void
+    {
+        $config = ContainerConfig::create()
+            ->withDefinitions($definitions);
+        $container = new Container($config);
+
+        $object = $container->get($id);
+
+        self::assertInstanceOf(LazyLoadingInterface::class, $object);
+    }
+
+    public function lazyDefinitionDataProvider(): array
+    {
+        return [
+            'class as definition name' => [
+                [
+                    EngineMarkOne::class => [
+                        'lazy' => true,
+                    ],
+                ],
+                EngineMarkOne::class,
+            ],
+            'class as key' => [
+                [
+                    EngineMarkOne::class => [
+                        'class' => EngineMarkOne::class,
+                        'lazy' => true,
+                    ],
+                ],
+                EngineMarkOne::class,
+            ],
+            'alias as key' => [
+                [
+                    'mark_one' => [
+                        'class' => EngineMarkOne::class,
+                        'lazy' => true,
+                    ],
+                ],
+                'mark_one',
+            ],
+            'dedicated array definition' => [
+                [
+                    EngineMarkOne::class => [
+                        'definition' => ['class' => EngineMarkOne::class],
+                        'lazy' => true,
+                    ],
+                ],
+                EngineMarkOne::class,
+            ],
+            'dedicated callback definition' => [
+                [
+                    EngineMarkOne::class => [
+                        'definition' => fn () => new EngineMarkOne(),
+                        'lazy' => true,
+                    ],
+                ],
+                EngineMarkOne::class,
+            ],
+        ];
+    }
+}