Awesome
Acclimate - Container Adapters
Get Acclimated! Use any third-party dependency injection containers and service locators in your code by adapting them to a common container interface. Acclimate was created by Jeremy Lindblom.
Introduction
It seems like every framework has its own container object. They come in many shapes and sizes (service locator, service manager, service container, dependency injection (DI) container, registry, etc.), but are all generally used in a similar way.
The wide variety of implementations makes it hard for other frameworks, framework-agnostic libraries, or some applications to get the full benefits of using an inversion of control (IoC) system, because they either need to:
- Write their own container implementation (NIH Syndrome)
- Have a long-term dependency on a particular, third-party container implementation (and force that dependency on their users, which may already be using a different container implementation)
- Implement an abstraction layer to support one or more third-party containers
Acclimate is a library that does #3 for you. It provides a set of adapters for the most popular container implementations. This allows you to adapt, or "acclimate", instances of these containers to a common, normalized, and interoperable interface. Using Acclimate allows your framework, library, or application to retrieve items from the container objects of third-party libraries. That's interoperability!
The Container Interface
The ContainerInterface
used by Acclimate comes from the
container-interop/container-interop
project. It attempts
to normalize the various implementations of container interfaces (whether they be for service locators, dependency
injection containers, or something else similar) to a simple, readonly interface, that allows users to retrieve
entries from any third-party container in a consistent way.
The ContainerInterface
looks like this:
namespace Interop\Container;
interface ContainerInterface
{
/**
* @param string $id
* @return mixed
* @throws NotFoundException
* @throws ContainerException
*/
public function get($id);
/**
* @param string $id
* @return bool
*/
public function has($id);
}
Installation
Install the acclimate/container
package using Composer. This will also also install
container-interop/container-interop
, which provides the ContainerInterface
.
Warning: If you install Acclimate with dev dependencies, you will get A LOT of packages from various frameworks
(e.g., ZF, Symfony, Laravel, etc.). These packages are required for testing only to ensure that all of the adapter
classes work correctly. They are not included when you run Composer with --no-dev
.
Note: We recommend using Composer and Composer's autoloader to load this library. If you are not using Composer's autoloader, be sure to use a PSR-4 compliant autoloader and map the namespace prefix Acclimate\Container\
to the src/
directory in order to correct autoload the classes.
Basic Usage
Acclimate: Container provides a ContainerAcclimator
object that is used to adapt a container object to a
normalized ContainerInterface
. In terms of design patterns, it's essentially a factory for adapters.
Here is an example of how to use the ContainerAcclimator
:
<?php
// Require the Composer autoloader
require 'vendor/autoload.php';
use Acclimate\Container\ContainerAcclimator;
// Create a `Pimple` container and store an `SplQueue` object in it
$pimple = new Pimple();
$pimple['queue'] = function() {
$queue = new SplQueue();
$queue->enqueue('Hello!');
return $queue;
};
// Create a `ContainerAcclimator` and use it to adapt the `Pimple` container to the Acclimate `ContainerInterface`
$acclimator = new ContainerAcclimator;
$container = $acclimator->acclimate($pimple);
// Use the adapted container via the common interface to fetch the queue object
$queue = $container->get('queue');
echo $queue->dequeue(); // Look! The queue object still works!
#> Hello!
Now you can use the container from your favorite framework and acclimate it into your other code. :-)
Container Decorators
The default behavior of a container implementing the ContainerInterface
is to throw a
Interop\Container\Exception\NotFoundException
when using get()
to retrieve an entry that does not actually exist in
the container. In some cases, you may want to change this default behavior to do something else instead (e.g., return
null
). Container decorators allow you to easily modify the behavior of a container. acclimate\container
ships with
3 decorators (NullOnMissContainer
, CallbackOnMissContainer
, and FailoverOnMissContainer
), but allows you to easily
create your own by extending Acclimate\Container\Decorator\AbstractContainerDecorator
.
Here is an example of how to use the NullOnMissContainer
decorator:
<?php
// Require the Composer autoloader
require 'vendor/autoload.php';
use Acclimate\Container\ArrayContainer;
use Acclimate\Container\Decorator\NullOnMissContainer;
use Interop\Container\Exception\NotFoundException;
// Create an empty, basic container following the `ContainerInterface`
$container = new ArrayContainer();
// Normally, this container will throw an exception on missing items
try {
$item = $container->get('foo');
} catch (NotFoundException $e) {
echo $e->getMessage() . "\n";
}
# There is no entry found in the container for the identifier "foo".
// Decorate the container so that null is returned instead of throwing an exception
$container = new NullOnMissContainer($container);
$item = $container->get('foo');
var_dump($item);
#> NULL
Composite Container
You can create composite containers if your use case requires that you need to fetch data from two or more different
container objects. For the sake of the following example, we will say the you have a Symfony Container
stored in the
variable $sfContainer
, and a Zend ServiceManager
stored in the variable $zfContainer
.
use Acclimate\Container\ContainerAcclimator;
use Acclimate\Container\CompositeContainer;
// First, let's acclimate these containers
$acclimator = new ContainerAcclimator;
$sfContainer = $acclimator->acclimate($sfContainer);
$zfContainer = $acclimator->acclimate($zfContainer);
// Now, we will put these two containers together
$container = new CompositeContainer([$sfContainer, $zfContainer]);
// When we execute the `has()` method of the container, it will return `true`
// if at least one of these containers contains an item identified by "foo"
$exists = $container->has('foo');
This is essentially a way to support container chaining, but uses the Composite design pattern instead of the Chain of
Command design pattern. You can also use the FailoverOnMissContainer
decorator to support chaining.
Supported Containers
- Aura.Di Container
- Laravel Container
- League Container
- Nette DI Container
- PHP-DI Container
- Pimple
- Symfony Dependency Injection Container
- ZF2 Dependency Injection
- ZF2 Service Manager
- ZF2 Dependency Injection
- Phalcon DI
- Any other container-like object that implements
ArrayAccess
(seeArrayAccess
in the PHP Manual)
Also, the Silex Application and other projects descending from Pimple can be used with Acclimate as well.
Deprecated Containers
Support for the following containers is deprecated in version 1.1, and will be removed in 2.0:
What if the Container I use is not supported?
Please consider submitting a Pull Request with an adapter for your container and a corresponding test.
Before you get to that point though, you can create the adapter yourself (which is really easy to do actually, just
look at the included ones), and use the ContainerAcclimator::registerAdapter()
method to wire up your adapter to
Acclimate. You will need to provide the fully qualified class name (FQCN) of both the adapter class and the base class
or interface of the container you want to be able to adapt (the "adaptee").
Assuming that you have a $container
object that implements Your\Favorite\ContainerInterface
, and you have written an
adapter class named Your\Favorite\ContainerAdapter
, here is an example of how you can make these work in Acclimate:
use Acclimate\Container\ContainerAcclimator;
// Instantiate the `ContainerAcclimator` and register your custom adapter
$acclimator = new ContainerAcclimator;
$acclimator->registerAdapter('Your\Favorite\ContainerAdapter', 'Your\Favorite\ContainerInterface');
// Use Acclimate to adapt your container
$adaptedContainer = $acclimator->acclimate($container);