Add Ref for named container references in Autowire

Ref is a value object that maps a constructor parameter to a container
key, enabling Autowire for cases where type-based resolution is
insufficient (same interface with multiple implementations, or builtin
types like array/string).

Author: alganet

src/Autowire.php

@@ -28,7 +28,13 @@ protected function cleanupParams(array $params): array
             foreach ($constructor->getParameters() as $param) {
                 $name = $param->getName();
                 if (array_key_exists($name, $this->params)) {
-                    $params[$name] = $this->lazyLoad($params[$name] ?? null);
+                    $value = $params[$name] ?? null;
+                    if ($value instanceof Ref) {
+                        $params[$name] = $this->container->get($value->id);
+                    } else {
+                        $params[$name] = $this->lazyLoad($value);
+                    }
+
                     continue;
                 }
 

src/Ref.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\Config;
+
+class Ref
+{
+    public function __construct(public readonly string $id)
+    {
+    }
+}

tests/AutowireTest.php

@@ -226,6 +226,77 @@ public function testAutowireWithoutContainerLazyLoadsParams(): void
         $this->assertEquals('lazy_loaded', $instance->dep->value);
     }
 
+    public function testRefResolvesClassDependencyByStringKey(): void
+    {
+        $container = new Container();
+        $dep = new AutowireDependency('via_ref');
+        $container['my.custom.dep'] = $dep;
+
+        $autowire = new Autowire(AutowireTypedConsumer::class);
+        $autowire->setContainer($container);
+        $autowire->setParam('dep', new Ref('my.custom.dep'));
+
+        $instance = $autowire->getInstance();
+        $this->assertSame($dep, $instance->dep);
+    }
+
+    public function testRefResolvesNonClassDependency(): void
+    {
+        $container = new Container();
+        $container['app.name'] = 'MyApp';
+
+        $autowire = new Autowire(AutowireWithBuiltin::class);
+        $autowire->setContainer($container);
+        $autowire->setParam('name', new Ref('app.name'));
+
+        $instance = $autowire->getInstance();
+        $this->assertEquals('MyApp', $instance->name);
+    }
+
+    public function testRefCoexistsWithTypeBasedAutowiring(): void
+    {
+        $container = new Container();
+        $container['DateTime'] = new DateTime('2024-01-15');
+        $container['custom.dep'] = new AutowireDependency('from_ref');
+
+        $autowire = new Autowire(AutowireMultiParam::class);
+        $autowire->setContainer($container);
+        // Only bind 'dep' via Ref; 'date' should be autowired by type
+        $autowire->setParam('dep', new Ref('custom.dep'));
+
+        $instance = $autowire->getInstance();
+        $this->assertInstanceOf(DateTime::class, $instance->date);
+        $this->assertEquals('from_ref', $instance->dep->value);
+    }
+
+    public function testRefTakesPrecedenceOverTypeBasedAutowiring(): void
+    {
+        $container = new Container();
+        $container['DateTime'] = new DateTime('2024-01-15');
+        $container[AutowireDependency::class] = new AutowireDependency('from_type');
+        $container['override.dep'] = new AutowireDependency('from_ref');
+
+        $autowire = new Autowire(AutowireTypedConsumer::class);
+        $autowire->setContainer($container);
+        $autowire->setParam('dep', new Ref('override.dep'));
+
+        $instance = $autowire->getInstance();
+        $this->assertEquals('from_ref', $instance->dep->value);
+    }
+
+    public function testRefResolvesArrayDependency(): void
+    {
+        $container = new Container();
+        $container['app.paths'] = ['/path/one', '/path/two'];
+
+        $autowire = new Autowire(AutowireWithArray::class);
+        $autowire->setContainer($container);
+        $autowire->setParam('paths', new Ref('app.paths'));
+
+        $instance = $autowire->getInstance();
+        $this->assertEquals(['/path/one', '/path/two'], $instance->paths);
+    }
+
     /** @return array<string, mixed> */
     private static function parseIni(string $ini): array
     {
@@ -284,3 +355,11 @@ public function __construct(public DateTime|null $a = null, public DateTime|null
     {
     }
 }
+
+class AutowireWithArray
+{
+    /** @param array<string> $paths */
+    public function __construct(public array $paths)
+    {
+    }
+}

tests/RefTest.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\Config;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use ReflectionProperty;
+
+#[CoversClass(Ref::class)]
+final class RefTest extends TestCase
+{
+    public function testConstructorSetsId(): void
+    {
+        $ref = new Ref('some.container.key');
+        $this->assertEquals('some.container.key', $ref->id);
+    }
+
+    public function testIdIsReadonly(): void
+    {
+        $ref = new Ref('my.key');
+        $reflection = new ReflectionProperty($ref, 'id');
+        $this->assertTrue($reflection->isReadOnly());
+    }
+}