Support class name references (aliases) in Container configuration

Author: clue

docs/best-practices/controllers.md

@@ -270,6 +270,32 @@ name to a factory function that will be invoked when this class is first
 requested. The factory function is responsible for returning an instance that
 implements the given class name.
 
+The container configuration may also be used to map a class name to a different
+class name that implements the same interface, either by mapping between two
+class names or using a factory function that returns a class name. This is
+particularly useful when implementing an interface.
+
+```php title="public/index.php"
+<?php
+
+use FrameworkX\Container;
+use Psr\Http\Message\ResponseInterface;
+use React\Cache\ArrayCache;
+use React\Cache\CacheInterface;
+use React\Http\Message\Response;
+
+// …
+
+$container = new Container([
+    ResponseInterface::class => Response::class,
+    CacheInterface::class => function () {
+        return ArrayCache::class;
+    }
+]);
+
+// …
+```
+
 ### PSR-11 compatibility
 
 > ⚠️ **Feature preview**

src/Container.php

@@ -9,14 +9,18 @@
  */
 class Container
 {
-    /** @var array<class-string,object|callable():object> */
+    /** @var array<class-string,object|callable():(object|class-string)> */
     private $container;
 
-    /** @var array<class-string,callable():object | object> */
+    /** @var array<class-string,callable():(object|class-string) | object | class-string> */
     public function __construct(array $map = [])
     {
         foreach ($map as $name => $value) {
-            if (!$value instanceof \Closure && !$value instanceof $name) {
+            if (\is_string($value)) {
+                $map[$name] = static function () use ($value) {
+                    return $value;
+                };
+            } elseif (!$value instanceof \Closure && !$value instanceof $name) {
                 throw new \BadMethodCallException('Map for ' . $name . ' contains unexpected ' . (is_object($value) ? get_class($value) : gettype($value)));
             }
         }
@@ -88,7 +92,13 @@ private function load(string $name, int $depth = 64)
             if ($this->container[$name] instanceof \Closure) {
                 $value = ($this->container[$name])();
 
-                if (!$value instanceof $name) {
+                if (\is_string($value)) {
+                    if ($depth < 1) {
+                        throw new \BadMethodCallException('Factory for ' . $name . ' is recursive');
+                    }
+
+                    $value = $this->load($value, $depth - 1);
+                } elseif (!$value instanceof $name) {
                     throw new \BadMethodCallException('Factory for ' . $name . ' returned unexpected ' . (is_object($value) ? get_class($value) : gettype($value)));
                 }
 

tests/ContainerTest.php

@@ -132,6 +132,76 @@ public function __invoke(ServerRequestInterface $request)
         $this->assertEquals('{"num":1}', (string) $response->getBody());
     }
 
+    public function testCallableReturnsCallableForClassNameWithExplicitlyMappedSubclassForDependency()
+    {
+        $request = new ServerRequest('GET', 'http://example.com/');
+
+        $dto = new class extends \stdClass { };
+        $dto->name = 'Alice';
+
+        $controller = new class(new \stdClass()) {
+            private $data;
+
+            public function __construct(\stdClass $data)
+            {
+                $this->data = $data;
+            }
+
+            public function __invoke(ServerRequestInterface $request)
+            {
+                return new Response(200, [], json_encode($this->data));
+            }
+        };
+
+        $container = new Container([
+            \stdClass::class => get_class($dto),
+            get_class($dto) => $dto
+        ]);
+
+        $callable = $container->callable(get_class($controller));
+        $this->assertInstanceOf(\Closure::class, $callable);
+
+        $response = $callable($request);
+        $this->assertInstanceOf(ResponseInterface::class, $response);
+        $this->assertEquals(200, $response->getStatusCode());
+        $this->assertEquals('{"name":"Alice"}', (string) $response->getBody());
+    }
+
+    public function testCallableReturnsCallableForClassNameWithSubclassMappedFromFactoryForDependency()
+    {
+        $request = new ServerRequest('GET', 'http://example.com/');
+
+        $dto = new class extends \stdClass { };
+        $dto->name = 'Alice';
+
+        $controller = new class(new \stdClass()) {
+            private $data;
+
+            public function __construct(\stdClass $data)
+            {
+                $this->data = $data;
+            }
+
+            public function __invoke(ServerRequestInterface $request)
+            {
+                return new Response(200, [], json_encode($this->data));
+            }
+        };
+
+        $container = new Container([
+            \stdClass::class => function () use ($dto) { return get_class($dto); },
+            get_class($dto) => function () use ($dto) { return $dto; }
+        ]);
+
+        $callable = $container->callable(get_class($controller));
+        $this->assertInstanceOf(\Closure::class, $callable);
+
+        $response = $callable($request);
+        $this->assertInstanceOf(ResponseInterface::class, $response);
+        $this->assertEquals(200, $response->getStatusCode());
+        $this->assertEquals('{"name":"Alice"}', (string) $response->getBody());
+    }
+
     public function testCtorThrowsWhenMapContainsInvalidInteger()
     {
         $this->expectException(\BadMethodCallException::class);
@@ -142,6 +212,21 @@ public function testCtorThrowsWhenMapContainsInvalidInteger()
         ]);
     }
 
+    public function testCallableReturnsCallableThatThrowsWhenFactoryReturnsInvalidClassName()
+    {
+        $request = new ServerRequest('GET', 'http://example.com/');
+
+        $container = new Container([
+            \stdClass::class => function () { return 'invalid'; }
+        ]);
+
+        $callable = $container->callable(\stdClass::class);
+
+        $this->expectException(\BadMethodCallException::class);
+        $this->expectExceptionMessage('Class invalid not found');
+        $callable($request);
+    }
+
     public function testCallableReturnsCallableThatThrowsWhenFactoryReturnsInvalidInteger()
     {
         $request = new ServerRequest('GET', 'http://example.com/');
@@ -157,6 +242,21 @@ public function testCallableReturnsCallableThatThrowsWhenFactoryReturnsInvalidIn
         $callable($request);
     }
 
+    public function testCallableReturnsCallableThatThrowsWhenFactoryIsRecursive()
+    {
+        $request = new ServerRequest('GET', 'http://example.com/');
+
+        $container = new Container([
+            \stdClass::class => \stdClass::class
+        ]);
+
+        $callable = $container->callable(\stdClass::class);
+
+        $this->expectException(\BadMethodCallException::class);
+        $this->expectExceptionMessage('Factory for stdClass is recursive');
+        $callable($request);
+    }
+
     public function testInvokeContainerAsMiddlewareReturnsFromNextRequestHandler()
     {
         $request = new ServerRequest('GET', 'http://example.com/');