Download the PHP package marcosdipaolo/container without Composer

PSR-11 Dependency Injection Container

A production-ready, lightweight PSR-11 compliant dependency injection container for PHP with automatic constructor wiring, lifecycle management, and circular dependency detection.

Features

✅ PSR-11 Compliant - Implements the standard ContainerInterface
✅ Automatic Wiring - Resolves constructor dependencies without configuration
✅ Lifecycle Management - Singleton, transient, and factory bindings
✅ Circular Dependency Detection - Catches infinite dependency loops at resolution time
✅ Reflection Caching - Optimized performance for repeated resolutions
✅ Type Safety - Comprehensive error messages with actionable guidance
✅ Fully Tested - Extensive PHPUnit test suite with high coverage
✅ Static Analysis - PHPStan level 10 compliant

Installation

Quick Start

Usage Guide

Automatic Wiring

The container can automatically resolve classes by analyzing their constructor dependencies:

Lifecycle Management

Singleton Binding

Returns the same instance every time:

Transient Binding

Creates a new instance every time:

Factory Binding

Custom resolution logic with full control:

Interface Binding

Bind interfaces to concrete implementations:

Custom Resolution

Use factory functions for complex setup:

API Reference

Constructor

Methods

set(string $id, callable|string $concrete, string $lifecycle = 'transient'): void

Register a binding with optional lifecycle:

singleton(string $id, callable|string $concrete): void

Register a singleton binding (single instance):

transient(string $id, callable|string $concrete): void

Register a transient binding (new instance each time):

factory(string $id, callable $factory): void

Register a factory binding:

get(string $id): mixed

Resolve a service from the container:

Throws NotFoundException if the service cannot be resolved.

has(string $id): bool

Check if a service is registered:

resolve(string $id): object

Resolve a class by name without prior registration:

Throws NotFoundException if the class doesn't exist.
Throws ContainerException if the class cannot be instantiated.

clearSingletons(): void

Clear all cached singleton instances:

Useful for testing.

clearReflectionCache(): void

Clear cached reflection metadata:

Useful for debugging or dynamic code generation scenarios.

Error Handling

The container provides detailed error messages to help with debugging:

Missing Type Hints

Solution: Add a type hint or use a factory function.

Union Types

Solution: Use a factory function to explicitly choose which type to inject.

Circular Dependencies

Solution: Break the circular dependency or use lazy-loading / property injection.

Built-in Type Without Default

Solution: Provide a default value or use a factory function.

Testing

The package includes a comprehensive test suite:

Performance Considerations

Reflection Caching

The container caches reflection metadata after first resolution:

Clear the cache if working with dynamically generated classes:

Singleton Pattern

Use singletons for expensive-to-create services:

PSR-11 Compliance

This container implements the Psr\Container\ContainerInterface and follows PSR-11 standards:

• Implements get(string $id): mixed
• Implements has(string $id): bool
• Throws Psr\Container\NotFoundExceptionInterface when services aren't found
• Throws Psr\Container\ContainerExceptionInterface for container errors

Best Practices

1. Use constructor dependency injection - Prefer constructor parameters over setter injection
2. Type hint everything - Enable automatic wiring with proper type hints
3. Use interfaces for bindings - Makes code more testable and maintainable
4. Register at bootstrap - Set up bindings in a single bootstrap file
5. Use factories for complex logic - When automatic wiring isn't enough
6. Avoid circular dependencies - Refactor to break cycles or use lazy-loading
7. Test with clearSingletons() - Reset state between tests

License

MIT License - see LICENSE file

Contributing

Contributions are welcome! Please ensure all tests pass and code meets PHPStan level max:

Need Help? Check the test suite for more examples and edge cases.