Download the PHP package flyokai/amphp-injector without Composer

flyokai/amphp-injector

User docs → AGENTS.md

A dependency injection container for PHP 8.1+ with weaver-based parameter resolution, ordered compositions, attribute-driven wiring, and lifecycle management.

flyokai/amphp-injector is a substantially-evolved descendant of amphp/injector. The container is now driven by weavers (composable parameter resolvers), built around an immutable Application that owns a Container and an Injector, with first-class support for Composition collections, PHP 8 attributes, lifecycle hooks, and alias resolution.

Heads up. Despite the package name and namespace, this is a fork. If you arrived here looking for upstream amphp/injector's Injector::make(), define(), share(), delegate() API — that API is gone. Read on for what replaced it.

Features

• Application — entry point that holds a Container and Injector, implements Lifecycle
• Definition helpers — singleton(), object(), value(), factory(), injectableFactory(), compositionFactory(), compositionItem()
• Weavers — names(), types(), runtimeTypes(), automaticTypes(), any() for parameter resolution
• PHP 8 attributes — #[ServiceParameter], #[SharedParameter], #[PrivateParameter], #[FactoryParameter(Class)]
• Compositions — CompositionOrdered with topological sort via before / after / depends
• Aliases — one-way interface → implementation via AliasResolverImpl
• Lifecycle — start() in dependency order, stop() in reverse
• Lazy proxies — pluggable via ProxyDefinition (see examples/proxy.php)

Installation

The package's composer.json replaces amphp/injector so the namespace Amp\Injector\… resolves to this fork.

Quick start

Build flow

1. Create a Definitions collection containing service / object / value / factory / composition definitions.
2. Create an Injector with a root Weaver (typically any(...) chaining several weavers).
3. Construct Application(injector, definitions, name, ?aliasResolver).
4. The Application calls definition->build($injector) for every definition and registers providers in the Container.
5. application->start() walks the providers and starts every Lifecycle instance in dependency order.
6. $container->get($id) retrieves services.
7. application->stop() stops in reverse order.

Definition helpers

singleton(Definition, mustStart = false)

Wraps any definition to cache the instance — subsequent get() calls return the same object. mustStart=true requires the service to be started before first get().

object(string $class, ?Arguments $arguments = null)

Prototype factory — creates a new instance via constructor reflection every call. Wrap in singleton() for sharing.

value(mixed $value)

Wraps a literal — no construction logic.

factory(\Closure $factory, ?Arguments $arguments = null)

Prototype factory from a closure. The closure can accept a ProviderContext to inspect the injection site:

injectableFactory(string $class, ?\Closure $factory = null, ?Arguments $arguments = null)

Returns a callable from the container, not an instance. Some parameters are pre-injected; remaining ones are passed at call time:

compositionFactory(\Closure $factory, ?Definitions $itemDefinitions = null, ?Arguments $arguments = null)

Creates a composition — a collection of items built from sub-definitions. The factory receives all items as named arguments.

compositionItem(Definition $definition, array $before = [], array $after = [], array $depends = [])

Wraps a definition as a CompositionItem for use inside CompositionOrdered:

Weavers

Weavers resolve constructor / function parameters to definitions. They're chained inside Arguments — first match wins.

names(array $definitions = [])

Resolves by parameter name — the most common weaver:

types(array $definitions = [])

Resolves by parameter type — explicit class → definition mapping. Also indexes parent classes / interfaces.

runtimeTypes(Definitions $defs, AliasResolver $aliasResolver)

Resolves via PHP 8 attributes on parameters. Supported attributes:

automaticTypes(Definitions $defs, AliasResolver $aliasResolver)

Auto-wires by type from all registered definitions. Returns a definition only if exactly one matches the type — ambiguous matches return null.

any(Weaver ...$weavers)

Tries multiple weavers in order, returns the first match. Typical setup:

Alias resolution

Maps interfaces to implementations via AliasResolverImpl. Aliases are one-way — requesting Foo yields FooImpl, but requesting FooImpl directly resolves through FooImpl's own definition.

Compositions (ordered collections)

CompositionOrdered items get topologically sorted via before / after / depends:

CompositionImpl is the simple unordered variant. Use selfFactory() as the factory closure for both.

Lifecycle

Services implementing Lifecycle are managed by the application:

• start() — called after every definition is built; walks the dependency graph; starts in dependency order
• stop() — called on shutdown; reverse order
• singleton($definition, mustStart: true) — service must be started before first get()
• SingletonProvider->lazy() — defer initialization to first get() instead of start()

Lazy proxies

Pluggable via custom Definitions using ocramius/proxy-manager. See examples/proxy.php:

The built-in ProxyDefinition currently throws not supported yet — provide your own Definition subclass.

Examples

The examples/ directory contains runnable scripts for every feature:

Gotchas

• Aliases are one-way. Interface ⇒ Impl lets you request the interface. Requesting Impl directly uses Impl's own definition, not the alias.
• Class names are normalised to lowercase internally — don't rely on case-sensitive keys.
• Ambiguous auto-wiring — if two definitions share a type, automaticTypes returns null. Disambiguate with names() or types().
• Circular dependencies are not detected — they cause infinite recursion. Refactor or use lazy singletons.
• Containers are immutable — every with() returns a clone; the Application holds the final reference.
• mustStart singletons — get() before application->start() throws LifecycleException.
• Variadic parameters — only supported via injectableFactory(). Plain factory() doesn't pass variadics through.
• Built-in ProxyDefinition is not implemented — see examples/proxy.php for a custom approach.

Differences from upstream amphp/injector

See also

• flyokai/application — uses this DI as the runtime container; see also vendor/flyokai/flyokai/docs/dependency-injection.md for diconfig structure
• flyokai/composition — module-level topological sort (different layer than CompositionOrdered)
• flyokai/generic — TunerContainer / ExecutionContainer use compositions internally
• Original: https://github.com/amphp/injector

License

MIT