Merge branch 'hotfix/542-container-docs' into release-3.0.0

Close #542

Author: weierophinney

CHANGELOG.md

@@ -24,6 +24,14 @@ All notable changes to this project will be documented in this file, in reverse
   The related factories now consume these services in order to receive a
   response prototype for the services they produce.
 
+- [#542](https://github.com/zendframework/zend-expressive/pull/542) modifies the
+  `composer.json` to no longer suggest the pimple/pimple package, but rather the
+  zendframework/zend-pimple-config package.
+
+- [#542](https://github.com/zendframework/zend-expressive/pull/542) modifies the
+  `composer.json` to no longer suggest the aura/di package, but rather the
+  zendframework/zend-auradi-config package.
+
 ### Deprecated
 
 - Nothing.

README.md

@@ -73,10 +73,10 @@ can recommend the following implementations:
 
 - [zend-servicemanager](https://github.com/zendframework/zend-servicemanager):
   `composer require zendframework/zend-servicemanager`
-- [Pimple](https://github.com/silexphp/Pimple):
-  `composer require pimple/pimple`
-- [Aura.Di](https://github.com/auraphp/Aura.Di):
-  `composer require aura/di`
+- [Pimple](https://github.com/silexphp/Pimple) (see [docs](docs/book/features/container/pimple.md) for more details):
+  `composer require zendframework/zend-pimple-config`
+- [Aura.Di](https://github.com/auraphp/Aura.Di) (see [docs](docs/book/features/container/aura-di.md) for more details):
+  `composer require zendframework/zend-auradi-config`
 
 Additionally, you may optionally want to install a template renderer
 implementation, and/or an error handling integration. These are covered in the

composer.json

@@ -49,10 +49,10 @@
     },
     "suggest": {
         "filp/whoops": "^2.1 to use the Whoops error handler",
+        "zendframework/zend-auradi-config": "^1.0 to use Aura.Di dependency injection container",
         "zendframework/zend-expressive-helpers": "^3.0 for its UrlHelper, ServerUrlHelper, and BodyParseMiddleware",
-        "aura/di": "^3.2 to make use of Aura.Di dependency injection container",
-        "pimple/pimple": "^3.2.2 to use Pimple for dependency injection",
         "zendframework/zend-expressive-tooling": "For migration and development tools; require it with the --dev flag",
+        "zendframework/zend-pimple-config": "^1.0 to use Pimple for dependency injection container",
         "zendframework/zend-servicemanager": "^3.3 to use zend-servicemanager for dependency injection"
     },
     "autoload": {

docs/book/features/container/aura-di.md

@@ -11,127 +11,45 @@ injection container with the following features:
 - instance factories.
 - optional auto-resolution of typehinted constructor parameter values.
 
-## Installing Aura.Di
+## Installing and configuring Aura.Di
 
 Aura.Di implements [container-interop](https://github.com/container-interop/container-interop)
-as of version 3.
+as of version 3. To use Aura.Di as a dependency injection container, we
+recommend using [zendframework/zend-auradi-config](https://github.com/zendframework/zend-auradi-config),
+which helps you to configure its container. First install the package:
 
 ```bash
-$ composer require aura/di
+$ composer require zendframework/zend-auradi-config
 ```
 
-## Configuration
-
-Aura.Di can help you to organize your code better with
-[ContainerConfig classes](http://auraphp.com/packages/Aura.Di/config.html) and
-[two step configuration](http://auraphp.com/blog/2014/04/07/two-stage-config/).
-In this example, we'll put that in `config/container.php`:
+To configure Aura.Di, create the file `config/container.php` with the following
+contents:
 
 ```php
 <?php
-use Aura\Di\ContainerBuilder;
+use Zend\AuraDi\Config\Config;
+use Zend\AuraDi\Config\ContainerFactory;
 
-$containerBuilder = new ContainerBuilder();
+$config  = require __DIR__ . '/config.php';
+$factory = new ContainerFactory();
 
-// Use the builder to create and configure a container using an array of
-// ContainerConfig classes. Make sure the classes can be autoloaded!
-return $containerBuilder->newConfiguredInstance([
-    'Application\Config\Common',
-]);
+return $factory(new Config($config));
 ```
 
-The bare minimum `ContainerConfig` code needed to make zend-expressive work is:
-
-```php
-<?php
-// In src/Config/Common.php:
-namespace Application\Config;
-
-use Aura\Di\Container;
-use Aura\Di\ContainerConfig;
-use Aura\Router\Generator;
-use Aura\Router\RouteCollection;
-use Aura\Router\RouteFactory;
-use Aura\Router\Router;
-use Zend\Escaper\Escaper;
-use Zend\Expressive\Application;
-use Zend\Expressive\Container as ExpressiveContainer;
-use Zend\Expressive\Delegate;
-use Zend\Expressive\Middleware;
-use Zend\Expressive\Plates\PlatesRenderer;
-use Zend\Expressive\Router\AuraRouter;
-use Zend\Expressive\Router\Route;
-use Zend\Expressive\Router\RouterInterface;
-use Zend\Expressive\Template\TemplateRendererInterface;
-
-class Common extends ContainerConfig
-{
-    public function define(Container $di)
-    {
-        $di->params[RouteCollection::class] = array(
-            'route_factory' => $di->lazyNew(RouteFactory::class),
-        );
-        $di->params[Router::class] = array(
-            'routes' => $di->lazyNew(RouteCollection::class),
-            'generator' => $di->lazyNew(Generator::class),
-        );
-        $di->params[AuraRouter::class]['router'] = $di->lazyNew(Router::class);
-        $di->set(RouterInterface::class, $di->lazyNew(AuraRouter::class));
-        $di->set(Container\NotFoundDelegateFactory::class, $di->lazyNew(ExpressiveContainer\NotFoundDelegateFactory::class));
-        $di->set(Delegate\NotFoundDelegate::class, $di->lazyGetCall(ExpressiveContainer\NotFoundDelegateFactory::class, '__invoke', $di));
-        $di->set('Zend\Expressive\Delegate\DefaultDelegate', $di->lazyGetCall(ExpressiveContainer\NotFoundDelegateFactory::class, '__invoke', $di));
-        $di->set(Container\ApplicationFactory::class, $di->lazyNew(ExpressiveContainer\ApplicationFactory::class));
-        $di->set(Application::class, $di->lazyGetCall(ExpressiveContainer\ApplicationFactory::class, '__invoke', $di));
-
-        // Not Found handler
-        $di->set(Middleware\NotFoundHandler::class, $di->lazyGetCall(ExpressiveContainer\NotFoundHandlerFactory::class, '__invoke', $di));
-
-        // Templating
-        // In most cases, you can instantiate the template renderer you want to use
-        // without using a factory:
-        $di->set(TemplateRendererInterface::class, $di->lazyNew(PlatesRenderer::class));
-
-        // These next two can be added in any environment; they won't be used unless
-        // you add the WhoopsErrorResponseGenerator as the ErrorResponseGenerator implementation:
-        $di->set(ExpressiveContainer\WhoopsFactory::class, $di->lazyNew(ExpressiveContainer\WhoopsFactory::class));
-        $di->set('Zend\Expressive\Whoops', $di->lazyGetCall(ExpressiveContainer\WhoopsFactory::class, '__invoke', $di));
-        $di->set(ExpressiveContainer\WhoopsPageHandlerFactory::class, $di->lazyNew(ExpressiveContainer\WhoopsPageHandlerFactory::class));
-        $di->set('Zend\Expressive\WhoopsPageHandler', $di->lazyGetCall(ExpressiveContainer\WhoopsPageHandlerFactory::class, '__invoke', $di));
-
-        // Error Handling
-        $di->set('Zend\Stratigility\Middleware\ErrorHandler', $di->lazyGetCall(ExpressiveContainer\ErrorHandlerFactory::class, '__invoke', $di));
-
-        // If in development:
-        $di->set(ExpressiveContainer\WhoopsErrorResponseGeneratorFactory::class, $di->lazyNew(ExpressiveContainer\WhoopsErrorResponseGeneratorFactory::class));
-        $di->set(Middleware\ErrorResponseGenerator::class, $di->lazyGetCall(ExpressiveContainer\WhoopsErrorResponseGeneratorFactory::class, '__invoke', $di));
-
-        // If in production:
-        // $di->set(Middleware\ErrorResponseGenerator::class, $di->lazyGetCall(Container\ErrorResponseGeneratorFactory::class, '__invoke', $di));
-    }
-
-    public function modify(Container $di)
-    {
-        /*
-        $router = $di->get(RouterInterface::class);
-        $router->addRoute(new Route('/hello/{name}', function ($request, $response, $next) {
-            $escaper = new Escaper();
-            $name = $request->getAttribute('name', 'World');
-            $response->getBody()->write('Hello ' . $escaper->escapeHtml($name));
-            return $response;
-        }, Route::HTTP_METHOD_ANY, 'hello'));
-        */
-    }
-}
-```
+For more information, please see the
+[zend-auradi-config documentation](https://github.com/zendframework/zend-auradi-config/blob/master/README.md).
 
 Your bootstrap (typically `public/index.php`) will then look like this:
 
 ```php
 chdir(dirname(__DIR__));
 require 'vendor/autoload.php';
+
 $container = require 'config/container.php';
 $app = $container->get(Zend\Expressive\Application::class);
+
 require 'config/pipeline.php';
 require 'config/routes.php';
+
 $app->run();
 ```

docs/book/features/container/pimple.md

@@ -1,114 +1,53 @@
 # Using Pimple
 
-[Pimple](http://pimple.sensiolabs.org/) is a widely used code-driven dependency
-injection container provided as a standalone component by SensioLabs. It
-features:
+[Pimple](http://pimple.sensiolabs.org/) 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
+## Installing and configuring Pimple
 
 Pimple implements [PSR-11 Container](https://github.com/php-fig/container)
-as of version 3.2.
+as of version 3.2. To use Pimple as a dependency injection container, we
+recommend using [zendframework/zend-pimple-config](https://github.com/zendframework/zend-pimple-config),
+which helps you to configure the PSR-11 container. First install the package:
 
 ```bash
-$ composer require pimple/pimple
+$ composer require zendframework/zend-pimple-config
 ```
 
-## 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`.
+Now, create the file `config/container.php` with the following contents:
 
 ```php
-use Pimple\Container as PimpleContainer;
-use Pimple\Psr11\Container as PsrContainer;
-use Zend\Expressive\Container;
-use Zend\Expressive\Plates\PlatesRenderer;
-use Zend\Expressive\Router;
-use Zend\Expressive\Template\TemplateRendererInterface;
-
-$container = new PimpleContainer();
-
-// Application and configuration
-$container['config'] = include 'config/config.php';
-$container['Zend\Expressive\Application'] = new Container\ApplicationFactory;
-
-// Routing
-// In most cases, you can instantiate the router you want to use without using a
-// factory:
-$container['Zend\Expressive\Router\RouterInterface'] = function (PimpleContainer $container) {
-    return new Router\Aura();
-};
-
-// Expressive 2.X: We'll provide a default delegate:
-$delegateFactory = new Container\NotFoundDelegateFactory();
-$container['Zend\Expressive\Delegate\DefaultDelegate'] = $delegateFactory;
-$container[Zend\Expressive\Delegate\NotFoundDelegate::class] = $delegateFactory;
-
-// Expressive 2.X: We'll provide a not found handler:
-$container[Zend\Expressive\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 (PimpleContainer $container) {
-    return new PlatesRenderer();
-};
-
-// These next two can be added in any environment; they won't be used unless:
-// - (Expressive 1.X): you add the WhoopsErrorHandler as the FinalHandler
-//   implementation:
-// - (Expressive 2.X): you add the WhoopsErrorResponseGenerator as the
-//   ErrorResponseGenerator implementation
-$container['Zend\Expressive\Whoops'] = new Container\WhoopsFactory();
-$container['Zend\Expressive\WhoopsPageHandler'] = new Container\WhoopsPageHandlerFactory();
-
-// Error Handling
-
-// - In Expressive 2.X, all environments:
-$container['Zend\Expressive\Middleware\ErrorHandler'] = new Container\ErrorHandlerFactory();
-
-// If in development:
-// - Expressive 1.X:
-$container['Zend\Expressive\FinalHandler'] = new Container\WhoopsErrorHandlerFactory();
-// - Expressive 2.X:
-$container[Zend\Expressive\Middleware\ErrorResponseGenerator::class] = new Container\WhoopsErrorResponseGeneratorFactory();
-
-// If in production:
-// - Expressive 1.X:
-$container['Zend\Expressive\FinalHandler'] = new Container\TemplatedErrorHandlerFactory();
-// - Expressive 2.X:
-$container[Zend\Expressive\Middleware\ErrorResponseGenerator::class] = new Container\ErrorResponseGeneratorFactory();
-
-return new PsrContainer($container);
+<?php
+use Zend\Pimple\Config\Config;
+use Zend\Pimple\Config\ContainerFactory;
+
+$config  = require __DIR__ . '/config.php';
+$factory = new ContainerFactory();
+
+return $factory(new Config($config));
 ```
 
+For more information, please see the
+[zend-pimple-config documentation](https://github.com/zendframework/zend-pimple-config/blob/master/README.md).
+
 Your bootstrap (typically `public/index.php`) will then look like this:
 
 ```php
 chdir(dirname(__DIR__));
+require 'vendor/autoload.php';
+
 $container = require 'config/container.php';
 $app = $container->get(Zend\Expressive\Application::class);
 
-// In Expressive 2.X:
 require 'config/pipeline.php';
 require 'config/routes.php';
 
-// All versions:
 $app->run();
 ```
-
-> ### Environments
->
-> In the example above, we provide two alternate definitions for
-> either the service `Zend\Expressive\FinalHandler` (Expressive 1.X) or the
-> service `Zend\Expressive\Middleware\ErrorResponseGenerator` (Expressive 2.X),
-> 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.