Versions documentation

This patch versions the documentation.

V1 docs were imported from the v1.1.1 tag, and pushed under a v1
subdirectory of `docs/book/`. A sibling `v2/` subdirectory was also
created, and the existing v2 docs were moved under that directory. The
v1-specific migration documentation was removed from the v2 tree,
leaving us with a single migration document for that tree.

v2 documentation was scrubbed of references to "version 1" and/or "since
v2"; users can go to the v1 documentation for that information.

All existing pages were updated to render as redirects, using a
combination of `<noscript>` tags and JS redirects.

The mkdocs configuration was updated:

- to rewrite all existing mappings to the v2 subdirectory
- to add links for the v1 docs
- to add hidden mappings for the existing redirect pages

I've tested builds locally, and all works as expected. Existing URIs
redirect to the correct v2 variants, and the navigation now uses v2
links.

Author: weierophinney

docs/book/cookbook/autowiring-routes-and-pipelines.md

@@ -1,210 +1,8 @@
-# How can I autowire routes and pipelines?
-
-Expressive 2.0 switches to _programmatic_ pipelines and routes, versus
-_configuration-driven_ pipelines and routing. One drawback is that with
-configuration-driven approaches, users could provide configuration via a module
-`ConfigProvider`, and automatically expose new pipeline middleware or routes;
-with a programmatic approach, this is no longer possible.
-
-Or is it?
-
-## Delegator Factories
-
-One possibility, available since the Expressive 2.X skeleton application, is to
-use _delegator factories_ on the `Zend\Expressive\Application` instance in order
-to inject these items.
-
-A _delegator factory_ is a factory that _delegates_ creation of an instance to a
-callback, and then operates on that instance for the purpose of altering the
-instance or providing a replacement (e.g., a decorator or proxy). The delegate
-callback usually wraps a service factory, or, because delegator factories
-_also_ return an instance, additional delegator factories. As such, you assign
-delegator _factories_, plural, to instances, allowing multiple delegator
-factories to intercept processing of the service initialization.
-
-For the purposes of this particular example, we will use delegator factories to
-both _pipe_ middleware as well as _route_ middleware.
-
-To demonstrate, we'll take the default pipeline and routing from the skeleton
-application, and provide it via a delegator factory instead.
-
-First, we'll create the class `App\Factory\PipelineAndRoutesDelegator`, with
-the following contents:
-
-```php
-<?php
-
-namespace App\Factory;
-
-use App\Action;
-use Psr\Container\ContainerInterface;
-use Zend\Expressive\Application;
-use Zend\Expressive\Helper\ServerUrlMiddleware;
-use Zend\Expressive\Helper\UrlHelperMiddleware;
-use Zend\Expressive\Middleware\ImplicitHeadMiddleware;
-use Zend\Expressive\Middleware\ImplicitOptionsMiddleware;
-use Zend\Expressive\Middleware\NotFoundHandler;
-use Zend\Stratigility\Middleware\ErrorHandler;
-
-class PipelineAndRoutesDelegator
-{
-    /**
-     * @param ContainerInterface $container
-     * @param string $serviceName Name of the service being created.
-     * @param callable $callback Creates and returns the service.
-     * @return Application
-     */
-    public function __invoke(ContainerInterface $container, $serviceName, callable $callback)
-    {
-        /** @var $app Application */
-        $app = $callback();
-
-        // Setup pipeline:
-        $app->pipe(ErrorHandler::class);
-        $app->pipe(ServerUrlMiddleware::class);
-        $app->pipeRoutingMiddleware();
-        $app->pipe(ImplicitHeadMiddleware::class);
-        $app->pipe(ImplicitOptionsMiddleware::class);
-        $app->pipe(UrlHelperMiddleware::class);
-        $app->pipeDispatchMiddleware();
-        $app->pipe(NotFoundHandler::class);
-
-        // Setup routes:
-        $app->get('/', Action\HomePageAction::class, 'home');
-        $app->get('/api/ping', Action\PingAction::class, 'api.ping');
-
-        return $app;
-    }
-}
-```
-
-> ### Where to put the factory
->
-> You will place the factory class in one of the following locations:
->
-> - `src/App/Factory/PipelineAndRoutesDelegator.php` if using the default, flat,
->   application structure.
-> - `src/App/src/Factory/PipelineAndRoutesDelegator.php` if using the
->   recommended, modular, application structure.
-
-Once you've created this, edit the class `App\ConfigProvider`; in it, we'll
-update the `getDependencies()` method to add the delegator factory:
-
-```php
-public function getDependencies()
-{
-    return [
-        /* . . . */
-        'delegators' => [
-            \Zend\Expressive\Application::class => [
-                Factory\PipelineAndRoutesDelegator::class,
-            ],
-        ],
-    ];
-}
-```
-
-> ### Where is the ConfigProvider class?
->
-> The `ConfigProvider` class is in one of the following locations:
->
-> - `src/App/ConfigProvider.php` if using the default, flat, application
->   structure.
-> - `src/App/src/ConfigProvider.php` using the recommended, modular, application
->   structure.
-
-> ### Why is an array assigned?
->
-> As noted above in the description of delegator factories, since each delegator
-> factory returns an instance, you can nest multiple delegator factories in
-> order to shape initialization of a service. As such, they are assigned as an
-> _array_ to the service.
-
-Once you've done this, you can remove:
-
-- `config/pipeline.php`
-- `config/routes.php`
-- The following lines from `public/index.php`:
-
-  ```php
-  // Import programmatic/declarative middleware pipeline and routing
-  // configuration statements
-  require 'config/pipeline.php';
-  require 'config/routes.php';
-  ```
-
-If you reload your application at this point, you should see that everything
-continues to work as expected!
-
-## Caution: pipelines
-
-Using delegator factories is a nice way to keep your routing and pipeline
-configuration close to the modules in which they are defined. However, there is
-a caveat: you likely should **not** register pipeline middleware in a delegator
-factory _other than within your root application module_.
-
-The reason for this is simple: pipelines are linear, and specific to your
-application. If one module pipes in middleware, there's no guarantee it will be
-piped before or after your main pipeline, and no way to pipe the middleware at a
-position in the middle of the pipeline!
-
-As such:
-
-- Use a `config/pipeline.php` file for your pipeline, **OR**
-- Ensure you only define the pipeline in a **single** delegator factory on your
-  `Application` instance.
-
-## Caution: third-party, distributed modules
-
-If you are developing a module to distribute as a package via
-[Composer](https://getcomposer.org/), **you should not autowire any delegator
-factories that inject pipeline middleware or routes in the `Application`**.
-
-Why?
-
-As noted in the above section, pipelines should be created exactly once, at
-the application level. Registering pipeline middleware within a distributable
-package will very likely not have the intended consequences.
-
-If you ship with pipeline middleware, we suggest that you:
-
-- Document the middleware, and where you anticipate it being used in the
-  middleware pipeline.
-- Document how to add the middleware service to dependency configuration, or
-  provide the dependency configuration via your module's `ConfigProvider`.
-
-With regards to routes, there are other considerations:
-
-- Routes defined by the package might conflict with the application, or with
-  other packages used by the application.
-
-- Routing definitions are typically highly specific to the router implementation
-  in use. As an example, each of the currently supported router implementations
-  has a different syntax for placeholders:
-
-    - `/user/:id` + "constraints" configuration to define constraints (zend-router)
-    - `/user/{id}` + "tokens" configuration to define constraints (Aura.Router)
-    - `/user/{id:\d+}` (FastRoute)
-
-- Your application may have specific routing considerations or design.
-
-You could, of course, detect what router is in use, and provide routing for each
-known, supported router implementation within your delegator factory. We even
-recommend doing exactly that. However, we note that such an approach does not
-solve the other two points above.
-
-However, we still recommend _shipping_ a delegator factory that would register
-your routes, since routes *are* often a part of module design; just **do not
-autowire** that delegator factory. This way, end-users who *can* use the
-defaults do not need to cut-and-paste routing definitions from your
-documentation into their own applications; they will instead opt-in to your
-delegator factory by wiring it into their own configuration.
-
-## Synopsis
-
-- We recommend using delegator factories for the purpose of autowiring routes,
-  and, with caveats, pipeline middleware:
-    - The pipeline should be created exactly once, so calls to `pipe()` should
-      occur in exactly _one_ delegator factory.
-- Distributable packages should create a delegator factory for _routes only_,
-  but _should not_ register the delegator factory by default.
+<noscript><meta http-equiv="refresh" content="0; url=v2/cookbook/autowiring-routes-and-pipelines/"></noscript>
+<script>
+  document.addEventListener("DOMContentLoaded", function (event) {
+    var uri = new URL(window.location.href);
+    uri.pathname = 'v2/cookbook/autowiring-routes-and-pipelines/';
+    window.location = uri.href;
+  });
+</script>

docs/book/cookbook/common-prefix-for-routes.md

@@ -1,45 +1,8 @@
-# How can I prepend a common path to all my routes?
-
-You may have multiple middlewares providing their own functionality:
-
-```php
-$middleware1 = new UserMiddleware();
-$middleware2 = new ProjectMiddleware();
-
-$app = AppFactory::create();
-$app->pipe($middleware1);
-$app->pipe($middleware2);
-
-$app->run();
-```
-
-Let's assume the above represents an API.
-
-As your application progresses, you may have a mixture of different content, and now want to have
-the above segregated under the path `/api`.
-
-This is essentially the same problem as addressed in the
-["Segregating your application to a subpath"](../reference/usage-examples.md#segregating-your-application-to-a-subpath) example.
-
-To accomplish it:
-
-- Create a new application.
-- Pipe the previous application to the new one, under the path `/api`.
-
-```php
-$middleware1 = new UserMiddleware();
-$middleware2 = new ProjectMiddleware();
-
-$api = AppFactory::create();
-$api->pipe($middleware1);
-$api->pipe($middleware2);
-
-$app = AppFactory::create();
-$app->pipe('/api', $api);
-
-$app->run();
-```
-
-The above works, because every `Application` instance is itself middleware, and, more specifically,
-an instance of [Stratigility's `MiddlewarePipe`](https://github.com/zendframework/zend-stratigility/blob/master/doc/book/middleware.md),
-which provides the ability to compose middleware.
+<noscript><meta http-equiv="refresh" content="0; url=v2/cookbook/common-prefix-for-routes/"></noscript>
+<script>
+  document.addEventListener("DOMContentLoaded", function (event) {
+    var uri = new URL(window.location.href);
+    uri.pathname = 'v2/cookbook/common-prefix-for-routes/';
+    window.location = uri.href;
+  });
+</script>