FastForward\Container

A PSR-11 compliant aggregate container for PHP, designed to unify and resolve services across multiple container implementations. Includes native constructor autowiring and works with configuration objects and custom container stacks.

✨ Features

• Aggregates multiple containers
• Caches resolved entries
• Native constructor autowiring, including resolvable optional dependencies before defaults
• First-class support for configuration containers
• Incremental composition with ContainerBuilder
• PSR-11 compliant

🚀 Installation

composer require fast-forward/container

🛠️ Usage

For constructor autowiring without registrations:

use FastForward\Container\AutowireContainer;

$container = new AutowireContainer();
$service = $container->get(SomeService::class);

Concrete constructor dependencies are built recursively when their arguments can be inferred. Interfaces need explicit bindings, and required scalar arguments need a factory for the containing service.

To reuse an existing PSR-11 container, pass it as the delegate:

$container = new AutowireContainer($existingContainer);

The delegate's entries are looked up before autowiring, including for nested and optional object dependencies. Passing null is equivalent to omitting the delegate. Optional defaults apply to missing or uninferable dependencies. Construction failures and cycles remain errors when no other source resolves the entry. See the autowiring guide for complete examples.

To combine providers, configuration and several PSR-11 containers, use container(...). Earlier sources take precedence, with autowiring as the final fallback:

use FastForward\Container\ContainerInterface;
use function FastForward\Container\container;
use FastForward\Config\ArrayConfig;

$config = new ArrayConfig([
    ContainerInterface::class => [
        SomeServiceProvider::class, // strings will be initialized with a new call
        SomePsr11Container::class, // strings should be initializable with a simple new call
        new OtherServiceProvider('withArgument'), // objects that implement Interop\Container\ServiceProviderInterface
        new ServiceManager($dependencies), // objects that implement Psr\Container\ContainerInterface
    ],
]);

$container = container($config);

// or using the container function directly with a configuration variadic
// $container = container(
//     SomeServiceProvider::class,
//     SomePsr11Container::class,
//     new ApplicationConfig(), // that implements ConfigInterface with the ContainerInterface key
//     new OtherServiceProvider('withArgument'),
//     new ServiceManager($dependencies),
// );

// Retrieve service
$service = $container->get(SomeService::class);

The same composition is available through a static method:

use FastForward\Container\ContainerFactory;

$container = ContainerFactory::create($config);

Both forms accept the same variadic initializers. Each call creates a fresh aggregate, provider adapters, and autowiring container; supplied PSR-11 container objects are reused. Unsupported initializer classes raise InvalidArgumentException.

For conditional registration or setup across several stages, use the incremental builder:

use FastForward\Container\ContainerBuilder;

$builder = (new ContainerBuilder())->add($config);

if ($featureEnabled) {
    $builder->add($featureProvider);
}

$container = $builder->build();

add() accepts the same initializers and preserves registration order. Each build() creates a fresh composition; adding sources later affects subsequent builds only. Supplied source objects are reused, so independent composition caches do not imply cloning external containers or their services. ContainerFactory::create() delegates to this same builder implementation.

Agent skill

The bundled fast-forward-container skill guides agents through configuration, providers, factories, overrides and autowiring for fast-forward/container ^1.10. Earlier versions are outside its supported API contract. See the installation guide for optional automatic project installation with llm/skills, project/global copies, pinned Skills CLI commands, updates and removal.

📄 License

This package is licensed under the MIT License. See the LICENSE file for more details.

🔗 Links

• Repository
• Changelog
• Packagist
• RFC 2119
• PSR-11 Container Interface