Download the PHP package xtompie/container without Composer

Container

The Container class provides essential features for managing dependencies and class instances in a PHP application. It allows you to:

• Retrieve a single, shared container instance (singleton pattern).
• Automatically resolve class instances using reflection, including handling constructor dependencies.
• Bind interfaces to concrete classes for dependency injection.
• Alias one class to another, allowing different class implementations to be used interchangeably.
• Manage shared (singleton) instances, ensuring that the same instance is returned for multiple usages.
• Use service providers to control how specific services are resolved.
• Configure transient services, which return different instances each time they are accessed.

Requirements

• PHP >= 8

Installation

Using composer

Usage

Singleton

The Container class implements the singleton pattern, ensuring that the same instance of the container is used throughout the application. This is useful for managing global services and dependencies.

Get

The Container automatically resolves class instances using PHP's reflection capabilities. It inspects the class constructor to determine required dependencies and resolves them automatically.

Resolve

The Container class provides the resolve method, which allows you to pass specific values directly to a class's constructor when resolving dependencies. This is useful when you want to override or inject certain parameters that are not automatically resolvable by the container.

Unlike the get method, which can return shared instances, the resolve method always returns a new instance of the class, even if called multiple times. This ensures transient behavior and avoids shared state between instances.

In this example, the resolve() method manually provides the value quxx for the qux parameter, while the container automatically resolves the Foo dependency. Each call to resolve creates a new Bar instance.

Dependencies

If a class requires dependencies in its constructor, the Container resolves them as well. It inspects the constructor and creates instances of required classes.

Binding

You can bind an interface to a concrete class, allowing the container to resolve the correct implementation when the interface is requested.

Alias

The container allows you to alias one class to another, making it possible to use different class implementations interchangeably.

Shared

The container manages shared services, ensuring the same instance is returned each time the service is retrieved. This is useful for managing singletons.

Transient

Transient services return a new instance each time they are accessed. By marking a class as transient, the Container ensures that different instances are returned on every access.

You can either define a service as transient manually using the transient() method or implement the Transient interface to automatically mark a class as transient.

Alternatively, if a service class implements the Transient interface, the Container will automatically treat it as transient, meaning a new instance is returned on each retrieval:

In both cases, this ensures that transient objects are always new instances, as opposed to shared services, which return the same object every time.

Provider

Providers can be used for more complex service resolution. A provider is a class that implements the Provider interface, which allows you to control how specific services are created or managed within the container. Providers inject additional logic into the resolution process.

Here's the Provider interface:

To use a provider, first create a class that implements the Provider interface. The provide() method should return the service instance, and it will be invoked by the container when needed.

Example of a provider class:

You can then register the provider with the container and retrieve the service:

This approach allows for more complex or conditional logic when resolving services within the container.

Self-Providing Services

A service can provide its own provider by implementing the Provider interface. This allows a class to automatically supply instances for the container without needing to register the provider in the container.

If a class implements the Provider interface, the container will recognize this and automatically use it as a provider when creating instances.

In this example, the Qux class implements the Provider interface, meaning the container will automatically find the provider within the class and use it to create an instance. This removes the need to manually register the provider in the container.

Multi-binding

If you bind multiple classes, the container resolves the most concrete class available. This is useful for managing multiple levels of abstraction or class inheritance.

Call

Container class includes a call method that allows you to invoke any callback with automatic dependency injection. This method works for closures (anonymous functions), static class methods, and instance methods. The container automatically resolves and injects the required dependencies into the callback.

Using a closure (anonymous function):

In this example, the container automatically resolves the Foo dependency and injects it into the closure.

Using a static class method:

For static class methods, the container resolves the dependencies and injects them before invoking the static method.

Using an instance method:

Here, the container injects the Foo dependency into the instance method and then invokes the method on the provided object.

Call with values

The Container class includes a call method that allows you to invoke a callable with automatic dependency injection. Additionally, you can pass custom values that override the container's automatic resolution.

In this example:

• The Container resolves an instance of Foo.
• We pass a custom string value 'CustomName' for the $name parameter, which overrides the need for the container to resolve it.

callArgs

The callArgs method allows you to retrieve the arguments needed to call a given callable (function, method, etc.) with automatic dependency resolution. It inspects the callable’s parameters and resolves the necessary dependencies, optionally allowing custom values or a resolver to be used.

Custom Values

You can pass custom values to callArgs that override the container's default resolution behavior.

Custom Argument Resolver ($arg)

The callArgs method also accepts an optional $arg callable that resolves parameters before falling back to container resolution or custom values. If the $arg callable returns null, the resolution falls back to the container or the custom values.

In this case, the custom resolver takes precedence. If the resolver does not handle the argument (returns null), the container or provided custom values are used as fallback.

Key Points

• The $arg resolver has the highest priority.
• Custom values are checked next.
• If no match is found, the container will resolve dependencies automatically.

Extending

You can extend the Container class to add custom functionality or specific behavior for your application.

This allows you to tailor the container to meet the specific needs of your project, adding custom logic or behavior to the dependency resolution process.