Add PSR-11 Container support

Author: coisa

composer.json

@@ -13,6 +13,7 @@
         "php": "^8.1",
         "dflydev/dot-access-data": "^3.0",
         "laminas/laminas-config-aggregator": "^1.13",
+        "psr/container": "^1.0||^2.0",
         "psr/simple-cache": "^3.0"
     },
     "require-dev": {

src/Container/ConfigContainer.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/config.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/config
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Config\Container;
+
+use FastForward\Config\ConfigInterface;
+use FastForward\Config\Exception\ContainerNotFoundExceptionInterface;
+use Psr\Container\ContainerInterface;
+
+/**
+ * Class ConfigContainer.
+ *
+ * Provides a PSR-11 compatible container interface for accessing configuration values.
+ * This container MAY be used in dependency injection systems where configuration keys
+ * should be resolvable via standard container access.
+ */
+final class ConfigContainer implements ContainerInterface
+{
+    /**
+     * @const string The standard identifier for retrieving the configuration object.
+     */
+    public const ALIAS = 'config';
+
+    /**
+     * Constructs a new ConfigContainer instance.
+     *
+     * This constructor SHALL wrap an existing ConfigInterface instance and expose it
+     * through PSR-11 `get()` and `has()` methods.
+     *
+     * @param ConfigInterface $config the configuration instance to expose as a container
+     */
+    public function __construct(
+        private ConfigInterface $config,
+    ) {}
+
+    /**
+     * Determines if the container can return an entry for the given identifier.
+     *
+     * @param string $id identifier of the entry to look for
+     *
+     * @return bool TRUE if the entry is known or exists in the configuration, FALSE otherwise
+     */
+    public function has(string $id): bool
+    {
+        return $this->isResolvedByContainer($id)
+            || $this->config->has($id);
+    }
+
+    /**
+     * Retrieves an entry of the container by its identifier.
+     *
+     * If the ID matches the container itself or the config class, it SHALL return itself.
+     * Otherwise, it SHALL retrieve the value from the configuration.
+     * If the key is not found, it MUST throw a ContainerNotFoundExceptionInterface.
+     *
+     * @param string $id identifier of the entry to retrieve
+     *
+     * @return mixed the value associated with the identifier
+     *
+     * @throws ContainerNotFoundExceptionInterface if the identifier is not found
+     */
+    public function get(string $id)
+    {
+        if ($this->isResolvedByContainer($id)) {
+            return $this;
+        }
+
+        if ($this->config->has($id)) {
+            return $this->config->get($id);
+        }
+
+        throw ContainerNotFoundExceptionInterface::forKey($id);
+    }
+
+    /**
+     * Determines whether the given identifier is resolved internally by the container itself.
+     *
+     * This method SHALL be used to check if the requested identifier corresponds to:
+     * - the container alias (e.g., 'config'),
+     * - the Config interface (`FastForward\Config\ConfigInterface`),
+     * - or the concrete configuration key.
+     *
+     * If any of these conditions match, the container MUST resolve the request by returning itself.
+     *
+     * @param string $id the identifier being checked for internal resolution
+     *
+     * @return bool TRUE if the container SHALL resolve the identifier itself; FALSE otherwise
+     */
+    private function isResolvedByContainer(string $id): bool
+    {
+        return \in_array($id, [self::ALIAS, ConfigInterface::class, $this->config::class], true);
+    }
+}

src/Exception/ContainerNotFoundExceptionInterface.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/config.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/config
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Config\Exception;
+
+use Psr\Container\NotFoundExceptionInterface;
+
+/**
+ * Class ContainerNotFoundExceptionInterface.
+ *
+ * Exception thrown when a configuration key is not found in the container.
+ * This class MUST implement the PSR-11 NotFoundExceptionInterface.
+ */
+final class ContainerNotFoundExceptionInterface extends \Exception implements NotFoundExceptionInterface
+{
+    /**
+     * Creates a new exception instance for a missing configuration key.
+     *
+     * This factory method SHOULD be used when a key lookup fails in the ConfigContainer.
+     *
+     * @param string $key the key that was not found
+     *
+     * @return self a new instance of the exception describing the missing key
+     */
+    public static function forKey(string $key): self
+    {
+        return new self(\sprintf('Config key "%s" not found.', $key));
+    }
+}

tests/Container/ConfigContainerTest.php

@@ -0,0 +1,100 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/config.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/config
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Config\Tests\Container;
+
+use FastForward\Config\ArrayConfig;
+use FastForward\Config\ConfigInterface;
+use FastForward\Config\Container\ConfigContainer;
+use FastForward\Config\Exception\ContainerNotFoundExceptionInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\Attributes\UsesClass;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+#[CoversClass(ConfigContainer::class)]
+#[UsesClass(ArrayConfig::class)]
+#[UsesClass(ContainerNotFoundExceptionInterface::class)]
+final class ConfigContainerTest extends TestCase
+{
+    #[Test]
+    public function testHasReturnsTrueForKnownInternalIdentifiers(): void
+    {
+        $config    = new ArrayConfig();
+        $container = new ConfigContainer($config);
+
+        self::assertTrue($container->has(ConfigContainer::ALIAS));
+        self::assertTrue($container->has(ConfigInterface::class));
+        self::assertTrue($container->has($config::class));
+    }
+
+    #[Test]
+    public function testHasReturnsTrueIfConfigContainsKey(): void
+    {
+        $key   = uniqid('key_', true);
+        $value = uniqid('val_', true);
+
+        $config    = new ArrayConfig([$key => $value]);
+        $container = new ConfigContainer($config);
+
+        self::assertTrue($container->has($key));
+    }
+
+    #[Test]
+    public function testHasReturnsFalseForUnknownKey(): void
+    {
+        $config    = new ArrayConfig();
+        $container = new ConfigContainer($config);
+
+        self::assertFalse($container->has(uniqid('missing_', true)));
+    }
+
+    #[Test]
+    public function testGetReturnsContainerForInternalIdentifiers(): void
+    {
+        $config    = new ArrayConfig();
+        $container = new ConfigContainer($config);
+
+        self::assertSame($container, $container->get(ConfigContainer::ALIAS));
+        self::assertSame($container, $container->get(ConfigInterface::class));
+        self::assertSame($container, $container->get($config::class));
+    }
+
+    #[Test]
+    public function testGetReturnsConfigValueForKey(): void
+    {
+        $key   = uniqid('env_', true);
+        $value = uniqid('value_', true);
+
+        $config    = new ArrayConfig([$key => $value]);
+        $container = new ConfigContainer($config);
+
+        self::assertSame($value, $container->get($key));
+    }
+
+    #[Test]
+    public function testGetThrowsExceptionForUnknownKey(): void
+    {
+        $this->expectException(ContainerNotFoundExceptionInterface::class);
+
+        $config    = new ArrayConfig();
+        $container = new ConfigContainer($config);
+
+        $container->get(uniqid('unknown_', true));
+    }
+}

tests/Exception/ContainerNotFoundExceptionInterfaceTest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of php-fast-forward/config.
+ *
+ * This source file is subject to the license bundled
+ * with this source code in the file LICENSE.
+ *
+ * @link      https://github.com/php-fast-forward/config
+ * @copyright Copyright (c) 2025 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
+ * @license   https://opensource.org/licenses/MIT MIT License
+ */
+
+namespace FastForward\Config\Tests\Exception;
+
+use FastForward\Config\Exception\ContainerNotFoundExceptionInterface;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use Psr\Container\NotFoundExceptionInterface;
+
+/**
+ * @internal
+ */
+#[CoversClass(ContainerNotFoundExceptionInterface::class)]
+final class ContainerNotFoundExceptionInterfaceTest extends TestCase
+{
+    #[Test]
+    public function testForKeyReturnsExpectedMessage(): void
+    {
+        $key = uniqid('missing_', true);
+
+        $exception = ContainerNotFoundExceptionInterface::forKey($key);
+
+        self::assertInstanceOf(ContainerNotFoundExceptionInterface::class, $exception);
+        self::assertInstanceOf(NotFoundExceptionInterface::class, $exception);
+        self::assertSame(\sprintf('Config key "%s" not found.', $key), $exception->getMessage());
+    }
+}