README

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:

1. Write their own container implementation (NIH Syndrome)
2. 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)
3. 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 psr/container 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.

Acclimate v1 and previous use the similar container-interop/container-interop standard

The ContainerInterface looks like this:

namespace Psr\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 psr/container, 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 Psr\Container\NotFoundExceptionInterface 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 Psr\Container\NotFoundExceptionInterface;

// 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 (NotFoundExceptionInterface $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
• 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 (see ArrayAccess 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:

• Guzzle Service Builder

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);

Resources

• PSR-11 project
• Container Interop project
• Service container usage comparison