Download the PHP package ascetic-soft/wirebox without Composer

Wirebox

Lightweight PHP 8.4 DI container with autowiring, directory scanning, PHP attributes, and dotenv support.

📖 Full Documentation | Документация на русском | 中文文档

Features

• PSR-11 compatible (Psr\Container\ContainerInterface)
• Autowiring — automatic constructor dependency resolution via reflection
• Directory scanning — point at a directory, all classes are auto-registered
• PHP Attributes — #[Inject], #[Singleton], #[Transient], #[Lazy], #[Eager], #[Tag], #[Param], #[Exclude], #[AutoconfigureTag]
• Autoconfiguration — automatically tag services by interface or attribute (Symfony-style)
• Dotenv — built-in .env parser with 3-level priority (no external dependencies)
• Tagged services — group services by tag and retrieve them as a collection
• Lazy proxies — deferred instantiation via PHP 8.4 native lazy objects
• Compiled container — generate a PHP class with zero reflection at runtime
• Setter injection — configure method calls on services after instantiation
• Circular dependency detection — unsafe cycles detected at build time with clear error messages

Requirements

• PHP >= 8.4
• psr/container ^2.0

Installation

Quick Start

Configuration

ContainerBuilder

The ContainerBuilder is the main entry point for configuring the container.

The projectDir is used as the base path for resolving .env files.

Directory Scanning

Scan directories to auto-register all concrete classes (abstract classes, interfaces, traits, and enums are skipped):

Exclude files by glob pattern:

Classes marked with #[Exclude] are skipped automatically:

Interface Binding

Bind an interface to a concrete implementation:

When scanning, if an interface has exactly one implementation in the scanned directory, it is auto-bound automatically. If two or more implementations of the same interface are found, the auto-binding becomes ambiguous and build() will throw a ContainerException. Use an explicit bind() call to resolve the ambiguity:

Alternatively, if you don't need a specific binding but want to suppress the ambiguity error (e.g. the interface is resolved at runtime, or you only use tagged iteration), use excludeFromAutoBinding():

Multiple interfaces can be excluded at once:

Note: Unlike registerForAutoconfiguration(), this does not apply any autoconfiguration rules (tags, lifetime, etc.) — it only suppresses the ambiguity error.

Factory Registration

Register a service with a custom factory closure:

Fluent Definition API

Override or configure individual service definitions:

Parameters and Environment Variables

Set parameters that can reference environment variables:

Supported type casts: string (default), int, float, bool.

Parameters can also contain env expressions embedded in a larger string:

Environment Variables

Wirebox resolves environment variables with 3-level priority (highest first):

All files are resolved relative to projectDir.

.env File Format

Production: composer dump-env

For production, use Symfony's composer dump-env to generate .env.local.php:

This creates a PHP file that returns an array — no file parsing at runtime.

PHP Attributes

#[Singleton]

Marks a class as singleton (this is the default behavior, use for explicitness):

#[Transient]

A new instance is created on every get() call:

#[Lazy]

Return a lightweight proxy immediately; the real instance is created only when a property or method is first accessed. Uses PHP 8.4 native lazy objects (ReflectionClass::newLazyProxy):

Can be combined with #[Transient] to create a new lazy proxy on every get() call.

The same behavior is available via the fluent API:

Lazy proxies are fully supported by the compiled container.

Default lazy mode

ContainerBuilder enables lazy mode by default — all services without an explicit #[Lazy] or #[Eager] attribute are created as lazy proxies. You can disable this:

#[Eager]

Opt out of lazy instantiation when the container's default lazy mode is enabled:

The same behavior is available via the fluent API:

#[Tag]

Tag a class for grouped retrieval. Repeatable:

Retrieve tagged services:

#[AutoconfigureTag]

Automatically tag all classes that implement an interface or are decorated with a custom attribute. Place #[AutoconfigureTag] on the interface or attribute class.

On an interface — all implementing classes receive the tag:

On a custom attribute — all classes decorated with that attribute receive the tag:

Repeatable — multiple tags can be applied:

Programmatic Autoconfiguration

For more control (lifetime, lazy, multiple tags), use registerForAutoconfiguration() on the builder:

Any class implementing EventListenerInterface found during scan() will automatically get the event.listener tag, be configured as a singleton, and use lazy proxies.

This also works with attributes:

CQRS Example

Autoconfiguration makes it easy to set up command and query handlers:

Build and retrieve. Autoconfigured interfaces are excluded from the ambiguous auto-binding check, so multiple implementations work seamlessly:

#[Inject]

Specify a concrete implementation for a type-hinted parameter:

#[Param]

Inject a scalar value from environment variables:

The value is automatically cast to the parameter's type hint (string, int, float, bool).

#[Exclude]

Exclude a class from auto-registration during directory scanning:

Container API

PSR-11

Tagged Services

Parameters

Self-Resolution

The container registers itself under three keys, so you can type-hint whichever you prefer:

WireboxContainerInterface extends PSR-11 with getTagged(), getParameter(), and getParameters(). Both Container and CompiledContainer implement it.

Compiled Container

For production, compile the container to a PHP class. This eliminates reflection at runtime:

Use the compiled container in production:

The compiled container:

• Extends AsceticSoft\Wirebox\Compiler\CompiledContainer
• Implements WireboxContainerInterface (and PSR-11 ContainerInterface)
• Has a dedicated factory method for each service
• Supports singleton caching, interface bindings, parameters, and tags
• Binding aliases are folded into the method map at compile time for single-lookup resolution
• Does not support factory closures (they require runtime evaluation)

Circular Dependencies

Wirebox detects circular dependencies at build time (build() / compile()) and throws CircularDependencyException for unsafe cycles before the container is ever used.

When is a cycle safe?

A circular dependency is safe only when all services in the cycle are lazy singletons. The proxy is cached before real instantiation begins, so when the dependency chain loops back, it finds the proxy in the cache instead of re-entering construction:

When is a cycle unsafe?

Unsafe cycles are reported with a clear message:

Note: Factory-based definitions (register(..., fn() => ...)) are skipped during cycle analysis because their dependencies cannot be determined statically.

Error Handling

Wirebox throws specific exceptions for common issues:

All exceptions implement Psr\Container\ContainerExceptionInterface.

Full Example

Testing

License

MIT