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/Instantiator.php

@@ -2,6 +2,7 @@
 
 namespace Respect\Config;
 
+use InvalidArgumentException;
 use ReflectionClass;
 
 use function array_key_exists;
@@ -159,6 +160,10 @@ protected function cleanupParams(array $params): array
 
     protected function lazyLoad(mixed $value): mixed
     {
+        if ($value instanceof Ref) {
+            throw new InvalidArgumentException('Ref can only be used with Autowire, not ' . static::class);
+        }
+
         return $value instanceof self ? $value->getInstance() : $value;
     }
 

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/InstantiatorTest.php

@@ -5,6 +5,7 @@
 namespace Respect\Config;
 
 use DateTimeZone;
+use InvalidArgumentException;
 use PHPUnit\Framework\Attributes\CoversClass;
 use PHPUnit\Framework\TestCase;
 use stdClass;
@@ -198,6 +199,15 @@ public function testMethodCallWithNullArg(): void
         $this->assertTrue($s->ok);
     }
 
+    public function testRefThrowsInInstantiator(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Ref can only be used with Autowire');
+        $i = new Instantiator(stdClass::class);
+        $i->setParam('foo', new Ref('some.key'));
+        $i->getInstance();
+    }
+
     public function testStaticMethodReturningNonObject(): void
     {
         $i = new Instantiator(__NAMESPACE__ . '\\StaticNonObjectReturn');

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());
+    }
+}