[13.x] RFC: Lazy Services - New #[Lazy] Attribute

composer.json

@@ -15,7 +15,7 @@
         }
     ],
     "require": {
-        "php": "^8.3",
+        "php": "^8.4",
         "ext-ctype": "*",
         "ext-filter": "*",
         "ext-hash": "*",

src/Illuminate/Container/Attributes/Lazy.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Illuminate\Container\Attributes;
+
+use Attribute;
+
+#[Attribute]
+class Lazy
+{
+    //
+}

src/Illuminate/Container/Container.php

@@ -5,6 +5,7 @@
 use ArrayAccess;
 use Closure;
 use Exception;
+use Illuminate\Container\Attributes\Lazy;
 use Illuminate\Contracts\Container\BindingResolutionException;
 use Illuminate\Contracts\Container\CircularDependencyException;
 use Illuminate\Contracts\Container\Container as ContainerContract;
@@ -1058,8 +1059,16 @@ public function build($concrete)
 
         array_pop($this->buildStack);
 
+        if (!empty($reflector->getAttributes(Lazy::class))) {
+            $instance = $reflector->newLazyProxy(function () use ($concrete, $instances) {
+                return new $concrete(...$instances);
+            });
+        } else {
+            $instance = $reflector->newInstanceArgs($instances);
+        }
+
         $this->fireAfterResolvingAttributeCallbacks(
-            $reflector->getAttributes(), $instance = $reflector->newInstanceArgs($instances)
+            $reflector->getAttributes(), $instance
         );
 
         return $instance;

tests/Container/ContainerLazyTest.php

@@ -0,0 +1,133 @@
+<?php
+
+namespace Illuminate\Tests\Container;
+
+use Illuminate\Container\Attributes\Lazy;
+use Illuminate\Container\Container;
+use PHPUnit\Framework\TestCase;
+
+class ContainerLazyTest extends TestCase
+{
+    protected function tearDown(): void
+    {
+        Container::setInstance();
+    }
+
+    public function testConcreteDoesNotThrowsExceptionWithAttribute()
+    {
+        $container = new Container;
+        $lazy = $container->make(LazyWithAttributeStub::class);
+
+        // No RuntimeException has occurred
+        // LazyWithAttributeStub behaves like a Lazy Object, but this is not obvious from its type
+        $this->assertInstanceOf(LazyWithAttributeStub::class, $lazy);
+    }
+
+    public function testConcreteThrowsExceptionWithoutAttribute()
+    {
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage('Lazy call');
+
+        $container = new Container;
+        $container->make(LazyWithoutAttributeStub::class);
+    }
+
+    public function testConcreteDoesNotThrowsExceptionWithNoLogicConstructor()
+    {
+        $container = new Container;
+        $lazy = $container->make(LazyWithAttributeStub::class);
+
+        $this->assertInstanceOf(LazyWithAttributeStub::class, $lazy);
+
+        $this->assertSame('work', $lazy->work());
+    }
+
+    public function testConcreteDoesThrowsExceptionWithConstructorWithLogic()
+    {
+        $container = new Container;
+        $lazy = $container->make(LazyWithAttributeLogicStub::class);
+
+        // No RuntimeException has occurred so far
+        $this->assertInstanceOf(LazyWithAttributeLogicStub::class, $lazy);
+
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage('Lazy call');
+
+        // Only the call to number() causes a RuntimeException
+        $lazy->number();
+    }
+
+    public function testConcreteThrowsExceptionButNotLazyDependency()
+    {
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage('Parent call');
+
+        $container = new Container;
+        $container->make(LazyDependencyWithAttributeStub::class);
+    }
+
+    public function testConcreteNotLazyDependencyThrowsException()
+    {
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage('Lazy call');
+
+        $container = new Container;
+        $container->make(LazyDependencyWithoutAttributeStub::class);
+    }
+}
+
+#[Lazy]
+class LazyWithAttributeStub
+{
+    public function __construct()
+    {
+        throw new \RuntimeException('Lazy call');
+    }
+
+    public function work()
+    {
+        return 'work';
+    }
+}
+
+#[Lazy]
+class LazyWithAttributeLogicStub
+{
+    public $number;
+
+    public function __construct()
+    {
+        $this->number = 10;
+
+        throw new \RuntimeException('Lazy call');
+    }
+
+    public function number()
+    {
+        $this->number += 10;
+    }
+}
+
+class LazyWithoutAttributeStub
+{
+    public function __construct()
+    {
+        throw new \RuntimeException('Lazy call');
+    }
+}
+
+class LazyDependencyWithAttributeStub
+{
+    public function __construct(LazyWithAttributeStub $stub)
+    {
+        throw new \RuntimeException('Parent call');
+    }
+}
+
+class LazyDependencyWithoutAttributeStub
+{
+    public function __construct(LazyWithoutAttributeStub $stub)
+    {
+        throw new \RuntimeException('Parent call');
+    }
+}