Injector Laravel Package

Getting Started

Start by installing via Composer: composer require yiisoft/injector. The core class is Yiisoft\Injector\Injector, which you instantiate with optional configuration. Its simplest use case is automatic constructor injection—just call $injector->get(MyService::class) and it will resolve all constructor dependencies via reflection. For quick prototyping or small apps, this zero-configuration autowiring is often enough. Check the src/Injector.php source file first for signature clarity; the constructor signature is public function __construct(array $definitions = []), so begin defining overrides where needed (e.g., Injector::class => Injector::class for self-reference, or service interfaces to concrete implementations). No bootstrap file is strictly required—you can instantiate per-request or as a singleton in your app.

Note: This release supports PHP 7.4–8.5 (previously PHP 8.0+). Ensure your environment aligns with this constraint.

Implementation Patterns

• Service Location & Type Hints: Use $injector->get(SomeServiceInterface::class) in factories or controllers to obtain interface-typed services. Combine with typed properties (PHP 8+) for cleaner controllers: public function __construct(private SomeServiceInterface $service) {}.
• Definition Overrides: Prepend configuration arrays to override behavior. For example, [LoggerInterface::class => fn() => new FileLogger('app.log')]. Use Injector::build() to create partial definitions.
• Factory Patterns: For complex creation logic, define factories as callable definitions: [CachedClient::class => fn(Injector $injector) => new CachedClient($injector->get(HttpClient::class))].
• Lazy Resolution: Wrap expensive dependencies in lazy() (via Injector::lazy() helper) to defer instantiation until accessed.
• Method Injection: Use $injector->invoke([$service, 'methodName']) to inject arguments into non-constructor methods—useful for event handlers or console commands. Improved in 1.2.1: Debug traces for invoke() are now clearer, making it easier to identify resolution issues.
• Library Integration: Package your library with yiisoft/injector-compatible constructors (type-hinted, no hardcoded dependencies), enabling downstream apps to wire services without vendor lock-in.

Gotchas and Tips

• Circular Dependencies: The injector detects them (throws CircularReferenceException), but it doesn’t resolve them. Design with constructor immutability and prefer composition over deep chains.
• Reflection Limitations: Non-public constructors or properties won’t be injected—ensure constructors are public and properties use setter injection if needed (though not auto-wired). Use Injector::with() to customize reflection behavior if extending the package.
• Definition Priority: Definitions passed to the constructor take precedence over auto-wiring. Always double-check if you’re accidentally overriding a concrete class definition unintentionally.
• Debugging Failures:
  • When get() throws an NotFoundException or AmbiguousDependencyException, inspect the stack trace—the message includes the missing interface/concrete class and the class requesting it.
  • Improved in 1.2.1: Closure-based definitions now display more readable names in exception messages (PHP 8.4+), aiding debugging.
  • Enable DEBUG mode (if available in your version) to see full resolution paths.
• Performance: Reflection is cached internally in the Injector instance but runs on every get() call unless the definition is cached manually (e.g., via Injector::build() + serialize()/unserialize()). For production, pre-build and cache the injector configuration.
• Extensibility: You can extend Injector to add custom resolution logic (e.g., support for custom attributes), but prefer composition (e.g., middleware-like decorators) where possible—this package is designed to stay lean.