Download the PHP package maduser/argon-container without Composer

Argon Service Container

Argon is a high-performance, PSR-11 compliant dependency injection container with optional compilation.

It compiles your service graph into native PHP, eliminating reflection and runtime resolution overhead in production. Explicit bindings are preferred, but autowiring remains available when desired — allowing you to choose between strict, predictable behavior and dynamic flexibility.

Key Characteristics

• PSR-11 compliant
• Optional compilation to pure PHP
• Strict mode for explicit service registration
• Autowiring support when enabled
• No annotations, attributes, or external configuration formats
• Framework-agnostic

Strict vs Dynamic

Strict mode resolves only explicitly registered services and throws NotFoundException for unbound classes.

Dynamic mode (default) prefers explicit bindings but can autowire instantiable classes and invoke closures when no compiled binding exists.

Strictness can be enforced at runtime or baked into the compiled container.

Installation

Requires PHP 8.2+

Tests & QA

Usage

Binding and Resolving Services

Tip: Bind aliases or interfaces before registering the services that consume them. Resolution happens immediately, so the container can only error, not infer, when a dependency is missing.

By default, every binding is shared. Prefer transient lifecycles instead? Pass sharedByDefault: false to the constructor and opt specific services back into shared mode when needed:

Binding Arguments

When registering a service, you can provide constructor arguments using an associative array.
These arguments are matched by name to the constructor’s parameter list — no need for full signatures or complex configuration.

Set arguments during binding

These arguments are attached to the service binding and used every time it's resolved.

Pass arguments during resolution

For transient services, runtime arguments may vary on every call. For shared services, runtime arguments are accepted only before the shared instance has been created; after that, passing runtime arguments throws a ContainerException instead of silently ignoring them. Prefer binding arguments for stable singleton configuration.

Automatic Dependency Resolution

Argon will resolve Logger by class name, and skip env because it's optional. In strict mode, autowiring only works when you bind the dependency (as shown above); otherwise a NotFoundException is thrown.

What will NOT work in either mode:

In this case, you must bind the interface to a concrete class first and provide a default value for the primitive:

Parameter Registry

The parameter registry is a built-in key/value store used to centralize application configuration. It is fully compatible with the compiled container — values are embedded directly into the generated service code.

Use it to define reusable values, inject environment settings.

Set and retrieve values

Use parameters in bindings or at resolution

TIP: you can wrap the parameter registry with your own "ConfigRepository" and implement validation, scopes via dot notation, etc.

Factory Bindings

Use factory() to bind a service to a dedicated factory class.
The factory itself is resolved via the container and may define either an __invoke() method or a named method. Arguments bound to the product service, or passed to get() for the product service, are applied to the factory method only. If the factory object needs configuration, bind the factory class itself with its own arguments.

This resolves and calls ClockFactory::__invoke().

To use a specific method:

Contextual Bindings

Contextual bindings allow different consumers to receive different implementations of the same interface.

Service Providers

Service providers allow grouping service bindings and optional boot-time logic.

Interceptors

Think of interceptors as a tiny, service-aware middleware pipeline wrapped around the resolver.
Each interceptor:

• announces whether it applies by implementing a static supports() check (no global pipeline to walk for every service);
• can run before construction to tweak arguments or short-circuit with its own instance;
• can run after construction to decorate, validate, or otherwise finalise the resolved object.

Because they are scoped to specific services (or interfaces), you get the flexibility of middleware without forcing every resolution through a monolithic stack.

Compiled containers embed the same pre/post pipeline: when you call compile(), the current interceptors are snapshot and generated into the compiled get() method, so short-circuit logic and decorators behave exactly as they do at runtime.

Post-Resolution Interceptors

These are executed after a service is created, and can modify the object (e.g., inject metadata, call validation, register hooks).

Pre-Resolution Interceptors

These run before a service is instantiated. They can modify constructor parameters or short-circuit the entire resolution.

• Interceptors must implement either PreResolutionInterceptorInterface or PostResolutionInterceptorInterface.
• Both varieties require a static supports() method so only matching services trigger them.
• Pre-interceptors may short-circuit by returning an object; leaving null continues the pipeline.
• Interceptors are resolved lazily and only when matched.
• You can register as many interceptors as you want. They're evaluated in the order they were added.

Extending Services

extend() decorates a resolved service instance during runtime. It calls get() internally, so the service does not need to have been resolved before you extend it: a bound service is resolved immediately, then the decorated object replaces the binding for later calls.

From this point on, all calls to get(LoggerInterface::class) will return the wrapped instance.

In dynamic mode, extend() can also decorate an unbound concrete class that the container can autowire. In strict mode, or for missing non-autowireable IDs, it fails the same way get() would. Extending a transient binding currently replaces it with the decorated object for future resolutions.

Tags

Conditional Service Access

optional() is intentionally binding-based: it resolves the service only when a binding exists, otherwise it returns a no-op proxy. This is useful for optional collaborators, plugins, or integrations where "not registered" should mean "do nothing", even in dynamic mode where get() could autowire an unbound concrete class.

Closure Bindings with Autowired Parameters

Closure bindings are convenient for CLI tools, prototyping, or runtime-only services. Their parameters are resolved through the container at runtime, so dependencies can still be autowired.

Closures are not part of the compiled service graph. If a closure binding exists before compilation, either:

• register it during the boot() phase of a service provider, after the compiled container has been created;
• or explicitly mark it as excluded from compilation via skipCompilation().

Skipped closures are not embedded in the generated class. In dynamic compiled containers, class-based skipped bindings can still fall back to normal autowiring; non-class runtime services should be registered during boot.

Compiling the Container

The compiled container is a pure PHP class with zero runtime resolution logic for standard bindings. In strict mode the generated class omits the dynamic fallback entirely—missing registrations fail fast with NotFoundException. In magic mode it continues to fall back to the runtime resolver when needed.

When strictMode is omitted, the compiler mirrors the source container's current strict-mode setting. Pass strictMode: false explicitly to force a lenient compiled container from a strict runtime container.

ArgonContainer API

BindingBuilder API

When you call set(), it returns a BindingBuilder, which lets you configure the binding fluently.

Troubleshooting

• Circular dependency detected: The message Circular dependency detected for service '...'. means your dependencies form a loop (e.g., Foo → Bar → Foo). Refactor one side to depend on an interface, inject a factory, or defer the dependency until after construction—the container intentionally refuses to pick a side. Argon can’t stop you from wiring a loop; it just halts resolution before PHP spins forever.
• Service not found: A NotFoundException signals that no binding or autowireable class exists for the requested ID (or strict mode forbids the fallback). Verify the identifier, register a binding, or disable strict mode for dynamic lookups. The attached JSON DebugTrace shows which parameter triggered the lookup.
• Primitive parameter unresolved: Errors such as Cannot resolve primitive parameter '$env' happen when constructors require scalars with no default. Provide them when binding (set(Service::class, args: ['env' => 'prod'])), supply a contextual override, or make the constructor argument optional.
• Union type ambiguity: Union-typed dependencies are rejected unless a contextual binding points to exactly one concrete. Bind per consumer with $container->for(Consumer::class)->set(Interface::class, Implementation::class);.
• Factory argument mismatch: Missing required argument 'foo' raised from a factory method means the binding’s arguments didn’t cover the method signature. Pass overrides in $container->get(Service::class, ['foo' => ...]) or attach them to the binding via set(..., args: [...]).

When errors persist, inspect the DebugTrace::toJson() output embedded in exceptions—it captures the entire resolution path that led to the failure.

License

MIT License