Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
22 / 22
100.00%
1 / 1
 CRAP
n/a
0 / 0
FastForward\Container\container
100.00%
22 / 22
100.00%
1 / 1
 12
1<?php
2
3declare(strict_types=1);
4
5/**
6 * This file is part of php-fast-forward/container.
7 *
8 * This source file is subject to the license bundled
9 * with this source code in the file LICENSE.
10 *
11 * @copyright Copyright (c) 2025-2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12 * @license   https://opensource.org/licenses/MIT MIT License
13 *
14 * @see       https://github.com/php-fast-forward/container
15 * @see       https://github.com/php-fast-forward
16 * @see       https://datatracker.ietf.org/doc/html/rfc2119
17 */
18
19namespace FastForward\Container;
20
21use Throwable;
22use FastForward\Config\ConfigInterface;
23use FastForward\Config\Container\ConfigContainer;
24use FastForward\Container\Exception\InvalidArgumentException;
25use Interop\Container\ServiceProviderInterface;
26use Psr\Container\ContainerInterface as PsrContainerInterface;
27
28/**
29 * Creates and assembles a fully composed container instance.
30 *
31 * This factory function is responsible for composing a container from a list of initializers,
32 * which MAY include:
33 * - PSR-11 container instances
34 * - Service providers implementing ServiceProviderInterface
35 * - Configuration instances implementing ConfigInterface
36 * - Class names as strings (which MUST be instantiable)
37 *
38 * If a ConfigContainer is included, it SHALL attempt to resolve additional nested container
39 * definitions from its configuration using the key `${alias}.${ContainerInterface::class}`.
40 * Any invalid initializers MUST result in an InvalidArgumentException being thrown.
41 *
42 * The final container returned is an AutowireContainer that wraps an
43 * AggregateContainer composed of all resolved sources.
44 *
45 * @param ConfigInterface|PsrContainerInterface|ServiceProviderInterface|string ...$initializers
46 *                                                                                               A variadic list of container initializers, optionally including config or provider classes.
47 *
48 * @return ContainerInterface the composed and autowire-enabled container
49 *
50 * @throws InvalidArgumentException if an unsupported initializer type is encountered
51 */
52function container(
53    ConfigInterface|PsrContainerInterface|ServiceProviderInterface|string ...$initializers,
54): ContainerInterface {
55    $aggregateContainer = new AggregateContainer();
56
57    $getContainer = static fn($initializer): ?PsrContainerInterface => match (true) {
58        $initializer instanceof PsrContainerInterface    => $initializer,
59        $initializer instanceof ServiceProviderInterface => new ServiceProviderContainer(
60            $initializer,
61            $aggregateContainer
62        ),
63        $initializer instanceof ConfigInterface          => new ConfigContainer($initializer),
64        default                                          => null,
65    };
66
67    $resolve = static fn($initializer): ?PsrContainerInterface => match (true) {
68        \is_object($initializer)   => $getContainer($initializer),
69        class_exists($initializer) => $getContainer(new ($initializer)()),
70        default                    => throw InvalidArgumentException::forUnsupportedInitializer($initializer),
71    };
72
73    $configKey  = \sprintf('%s.%s', ConfigContainer::ALIAS, ContainerInterface::class);
74
75    foreach ($initializers as $initializer) {
76        $container = $resolve($initializer);
77        $aggregateContainer->append($container);
78
79        if ($container instanceof ConfigContainer) {
80            try {
81                foreach ($container->get($configKey) as $nested) {
82                    $aggregateContainer->append($resolve($nested));
83                }
84            } catch (Throwable) {
85                // Ignored
86            }
87        }
88    }
89
90    return new AutowireContainer($aggregateContainer);
91}