Using Pimple

Pimple is a widely used code-driven dependency injection container provided as a standalone component by SensioLabs. It features:

  • combined parameter and service storage.
  • ability to define factories for specific classes.
  • lazy-loading via factories.

Pimple only supports programmatic creation at this time.

Installing Pimple

Pimple does not currently (as of v3) implement PSR-11 Container; as such, you need to install the xtreamwayz/pimple-container-interop project, which provides a PSR-11 container wrapper around Pimple v3:

$ composer require xtreamwayz/pimple-container-interop

Configuring Pimple

To configure Pimple, instantiate it, and then add the factories desired. We recommend doing this in a dedicated script that returns the Pimple instance; in this example, we'll have that in config/container.php.

use Mezzio\Container;
use Mezzio\Plates\PlatesRenderer;
use Mezzio\Router;
use Mezzio\Template\TemplateRendererInterface;
use Xtreamwayz\Pimple\Container as Pimple;

$container = new Pimple();

// Application and configuration
$container['config'] = include 'config/config.php';
$container['Mezzio\Application'] = new Container\ApplicationFactory;

// Routing
// In most cases, you can instantiate the router you want to use without using a
// factory:
$container['Mezzio\Router\RouterInterface'] = function ($container) {
    return new Router\Aura();

// We'll provide a default delegate:
$delegateFactory = new Container\NotFoundDelegateFactory();
$container['Mezzio\Delegate\DefaultDelegate'] = $delegateFactory;
$container[Mezzio\Delegate\NotFoundDelegate::class] = $delegateFactory;

// We'll provide a not found handler:
$container[Mezzio\Middleware\NotFoundHandler::class] = new Container\NotFoundHandlerFactory();

// Templating
// In most cases, you can instantiate the template renderer you want to use
// without using a factory:
$container[TemplateRendererInterface::class] = function ($container) {
    return new PlatesRenderer();

// These next two can be added in any environment; they won't be used unless
// you add the WhoopsErrorResponseGenerator as the ErrorResponseGenerator
// implementation
$container['Mezzio\Whoops'] = new Container\WhoopsFactory();
$container['Mezzio\WhoopsPageHandler'] = new Container\WhoopsPageHandlerFactory();

// Error Handling

// - In all environments:
$container['Mezzio\Middleware\ErrorHandler'] = new Container\ErrorHandlerFactory();

// If in development:
$container[Mezzio\Middleware\ErrorResponseGenerator::class] = new Container\WhoopsErrorResponseGeneratorFactory();

// If in production:
$container[Mezzio\Middleware\ErrorResponseGenerator::class] = new Container\ErrorResponseGeneratorFactory();

return $container;

Your bootstrap (typically public/index.php) will then look like this:

$container = require 'config/container.php';
$app = $container->get(Mezzio\Application::class);

require 'config/pipeline.php';
require 'config/routes.php';

// All versions:


In the example above, we provide two alternate definitions for the service Mezzio\Middleware\ErrorResponseGenerator, one for development and one for production. You will need to add logic to your file to determine which definition to provide; this could be accomplished via an environment variable.