Docs updates for release

docs/4.x/strategies.md

@@ -6,6 +6,7 @@ sections:
     Applying Strategies: applying-strategies
     Application Strategy: application-strategy
     JSON Strategy: json-strategy
+    Default Response Behaviour: default-response-behaviour
     Custom Strategies: custom-strategies
 ---
 ## Introduction
@@ -100,9 +101,11 @@ function controller(ServerRequestInterface $request, array $args) : ResponseInte
 });
 ~~~
 
-### Exception Decorators
+### Exception (Throwable) Decorators
+
+The application strategy simply allows any `Throwable` to bubble out, you can catch them in your bootstrap process or you have the option to extend this strategy and overload the exception/throwable decorator methods. See [Custom Strategies](#custom-strategies).
 
-The application strategy simply allows any exceptions to bubble out, you can catch them in your bootstrap process or you have the option to extend this strategy and overload the exception decorator methods. See [Custom Strategies](#custom-strategies).
+*Note:* In version `5.x` exception decorators will be replaced completely with throwable decorators, keep this in mind when implementing custom strategies, recommendation is to proxy your exception decorator to the throwable decorator.
 
 ## JSON Strategy
 
@@ -195,6 +198,25 @@ $router->post('/acme', function (ServerRequestInterface $request) : ResponseInte
 | 429         | `League\Route\Http\Exception\TooManyRequestsException`            | The user has sent too many requests in a given amount of time.                                                                                                                                               |
 | 451         | `League\Route\Http\Exception\UnavailableForLegalReasonsException` | The resource is unavailable for legal reasons.                                                                                                                                                               |
 
+## Deafault Response Behaviour
+
+You can define default interactions/behavior for the response before it is sent.
+
+### Headers
+
+You can set a header to be applied to the response on every request, it will only be applied, if the header does not already exist. For example, you may want to set a custom `Content-Type` header.
+
+~~~php
+<?php declare(strict_types=1);
+
+$responseFactory = new Http\Factory\Diactoros\ResponseFactory;
+$strategy = new League\Route\Strategy\JsonStrategy($responseFactory);
+
+$strategy->setDefaultResponseHeader('content-type', 'acme-app/json');
+
+$router = (new League\Route\Router)->setStrategy($strategy);
+~~~
+
 ## Custom Strategies
 
 You can build your own custom strategy to use in your application as long as it is an implementation of `League\Route\Strategy\StrategyInterface`. A strategy is tasked with:

docs/_data/releases.yml

@@ -16,7 +16,7 @@
   name: League\Route 4.x
   type: Current
   requires: PHP >= 7.1.0
-  release: 4.0.1 - 2018-08
+  release: 4.2.0 - 2018-10
   support: Ongoing
   url: /4.x/
   menu:

docs/unstable/controllers.md

@@ -9,9 +9,9 @@ sections:
 ---
 ## Introduction
 
-Every defined route requires a `callable` to invoke when dispatched, something that could be described as a controller in MVC. By default, Route only imposes that the callable is defined with a specific signature, it is given a request object as the first argument, an associative array of wildcard route arguments as the second argument, and expects a response object to be returned. Read more about this in [HTTP](/unstable/http).
+Every defined route requires a `callable` to invoke when dispatched, something that could be described as a controller in MVC. By default, Route only imposes that the callable is defined with a specific signature, it is given a request object as the first argument, an associative array of wildcard route arguments as the second argument, and expects a response object to be returned. Read more about this in [HTTP](/4.x/http).
 
-This behaviour can be changed by creating/using a different strategy, read more about strategies [here](/unstable/strategies).
+This behaviour can be changed by creating/using a different strategy, read more about strategies [here](/4.x/strategies).
 
 ## Defining Controllers
 
@@ -266,4 +266,4 @@ $router->map('GET', '/', 'Acme\controller');
 
 ## Dependency Injection
 
-Where Route is instantiating the objects for your defined controller, a dependency injection container can be used to resolve those objects. Read more on dependency injection [here](/unstable/dependency-injection).
+Where Route is instantiating the objects for your defined controller, a dependency injection container can be used to resolve those objects. Read more on dependency injection [here](/4.x/dependency-injection).

docs/unstable/dependency-injection.md

@@ -12,7 +12,7 @@ Route has the ability to use a [PSR-11](https://www.php-fig.org/psr/psr-11/) dep
 
 ## Recommended Reading
 
-It is recommended that if you have limited or no knowledge of dependency injection you should read about the concepts before you attempt to implement it. A good place to get started is with the [Dependency Injection chapter](https://www.phptherightway.com/#dependency_injection) pf PHP The Right Way.
+It is recommended that if you have limited or no knowledge of dependency injection you should read about the concepts before you attempt to implement it. A good place to get started is with the [Dependency Injection chapter](https://www.phptherightway.com/#dependency_injection) of PHP The Right Way.
 
 ## Using a Container
 

docs/unstable/http.md

@@ -47,7 +47,7 @@ class SomeMiddleware implements MiddlewareInterface
 }
 ~~~
 
-Read more about middleware [here](/unstable/middleware).
+Read more about middleware [here](/4.x/middleware).
 
 ### Controller Signature
 
@@ -63,7 +63,7 @@ function controller(ServerRequestInterface $request) {
 }
 ~~~
 
-See more about controllers [here](/unstable/controllers).
+See more about controllers [here](/4.x/controllers).
 
 ### Request Input
 
@@ -73,7 +73,7 @@ Route does not provide any functionality for dealing with globals such as `$_GET
 
 Because Route is built around PSR-15, this means that middleware and controllers are handles in a [single pass](https://www.php-fig.org/psr/psr-15/meta/#52-single-pass-lambda) approach. What this means in practice is that all middleware is passed a request object but is expected to build and return its own response or pass off to the next middleware in the stack for that to create one. Any controller that is dispatched via Route is wrapped in a middleware that adheres to this.
 
-Once wrapped, your controller ultimately becomes the last middleware in the stack (this does not mean that it has to be invoked last, see [middleware](/unstable/middleware) for more on this), it just means that it will only be concerned with creating and returning a response object.
+Once wrapped, your controller ultimately becomes the last middleware in the stack (this does not mean that it has to be invoked last, see [middleware](/4.x/middleware) for more on this), it just means that it will only be concerned with creating and returning a response object.
 
 An example of a controller building a response might look like this.
 
@@ -91,4 +91,4 @@ function controller(ServerRequestInterface $request) : ResponseInterface {
 }
 ~~~
 
-Route does not provide any functionality for creating or interacting with a response object. For more information, please refer to the documentation of the [PSR-7](https://www.php-fig.org/psr/psr-7/) implementation that you have chosen to use.
+Route does not provide any functionality for creating or interacting with a response object. For more information, please refer to the documentation of the [PSR-7](https://www.php-fig.org/psr/psr-7/) implementation that you have chosen to use

docs/unstable/index.md

@@ -26,7 +26,7 @@ At its core is Nikita Popov's [FastRoute](https://github.com/nikic/FastRoute) pa
 
 ## What isn't Route?
 
-Route is not a framework, it will not allow you to build an application out of the box. See our [usage documentation](/unstable/usage) for more information.
+Route is not a framework, it will not allow you to build an application out of the box.
 
 ## Goals
 

docs/unstable/strategies.md

@@ -6,6 +6,7 @@ sections:
     Applying Strategies: applying-strategies
     Application Strategy: application-strategy
     JSON Strategy: json-strategy
+    Default Response Behaviour: default-response-behaviour
     Custom Strategies: custom-strategies
 ---
 ## Introduction
@@ -100,20 +101,22 @@ function controller(ServerRequestInterface $request, array $args) : ResponseInte
 });
 ~~~
 
-### Exception Decorators
+### Exception (Throwable) Decorators
+
+The application strategy simply allows any `Throwable` to bubble out, you can catch them in your bootstrap process or you have the option to extend this strategy and overload the exception/throwable decorator methods. See [Custom Strategies](#custom-strategies).
 
-The [application strategy](https://github.com/thephpleague/route/blob/master/src/Strategy/ApplicationStrategy.php) simply allows any exceptions to bubble out, you can catch them in your bootstrap process or you have the option to extend this strategy and overload the exception decorator methods. See [Custom Strategies](#custom-strategies).
+*Note:* In version `5.x` exception decorators will be replaced completely with throwable decorators, keep this in mind when implementing custom strategies, recommendation is to proxy your exception decorator to the throwable decorator.
 
 ## JSON Strategy
 
-`League\Route\Strategy\JsonStrategy` aims to make building JSON APIs a little easier. It provides a PSR-7 `Psr\Http\Message\ServerRequestInterface` implementation and any route arguments to the controller as with the application strategy, the difference being that you can either build and return a response yourself or return an array and a JSON response will be built for you.
+`League\Route\Strategy\JsonStrategy` aims to make building JSON APIs a little easier. It provides a PSR-7 `Psr\Http\Message\ServerRequestInterface` implementation and any route arguments to the controller as with the application strategy, the difference being that you can either build and return a response yourself or return an array or object, and a JSON response will be built for you.
 
 To make use of the JSON strategy, you will need to provide it with a [PSR-17](https://www.php-fig.org/psr/psr-17/) response factory implementation. Some examples of HTTP Factory packages can be found [here](https://github.com/http-interop?utf8=%E2%9C%93&q=http-factory&type=&language=). We will use the `zend-diactoros` factory as an example.
 
 ~~~php
 <?php declare(strict_types=1);
 
-$responseFactory = Http\Factory\Diactoros\ResponseFactory;
+$responseFactory = new Http\Factory\Diactoros\ResponseFactory;
 $strategy = new League\Route\Strategy\JsonStrategy($responseFactory);
 
 $router = (new League\Route\Router)->setStrategy($strategy);
@@ -195,6 +198,25 @@ $router->post('/acme', function (ServerRequestInterface $request) : ResponseInte
 | 429         | `League\Route\Http\Exception\TooManyRequestsException`            | The user has sent too many requests in a given amount of time.                                                                                                                                               |
 | 451         | `League\Route\Http\Exception\UnavailableForLegalReasonsException` | The resource is unavailable for legal reasons.                                                                                                                                                               |
 
+## Deafault Response Behaviour
+
+You can define default interactions/behavior for the response before it is sent.
+
+### Headers
+
+You can set a header to be applied to the response on every request, it will only be applied, if the header does not already exist. For example, you may want to set a custom `Content-Type` header.
+
+~~~php
+<?php declare(strict_types=1);
+
+$responseFactory = new Http\Factory\Diactoros\ResponseFactory;
+$strategy = new League\Route\Strategy\JsonStrategy($responseFactory);
+
+$strategy->setDefaultResponseHeader('content-type', 'acme-app/json');
+
+$router = (new League\Route\Router)->setStrategy($strategy);
+~~~
+
 ## Custom Strategies
 
 You can build your own custom strategy to use in your application as long as it is an implementation of `League\Route\Strategy\StrategyInterface`. A strategy is tasked with:

docs/unstable/usage.md

@@ -13,6 +13,7 @@ to install and manage your installation of Route. You'll [need to install][depen
 both the Route project and an implementation of the [PSR-7 message interface][psr7]. 
 
 First, install the Route project itself:
+
 ~~~
 composer require league/route
 ~~~
@@ -23,7 +24,7 @@ Next, install an implementation of PSR-7. We recommend the [Zend Diactoros proje
 composer require zendframework/zend-diactoros
 ~~~
 
-Optionally, you could also install a PSR-11 dependency injection container, see [Dependency Injection](/unstable/dependency-injection) for more information.
+Optionally, you could also install a PSR-11 dependency injection container, see [Dependency Injection](/4.x/dependency-injection) for more information.
 
 ~~~
 composer require league/container
@@ -64,6 +65,12 @@ $response = $router->dispatch($request);
 
 Only a few changes are needed to create a simple JSON API. We have to change the strategy that the router uses to dispatch a controller, as well as providing a response factory to ensure the JSON Strategy can build the response it needs to.
 
+To provide a response factory, we will need to install a http-interop response factory package, in this case we will use the factory for zend-diactoros.
+
+~~~
+composer require http-interop/http-factory-diactoros
+~~~
+
 ~~~php
 <?php declare(strict_types=1);
 
@@ -76,9 +83,7 @@ $request = Zend\Diactoros\ServerRequestFactory::fromGlobals(
     $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES
 );
 
-$responseFactory = function () : ResponseInterface {
-    return new Zend\Diactoros\Response;
-};
+$responseFactory = new Http\Factory\Diactoros\ResponseFactory;
 
 $strategy = new League\Route\Strategy\JsonStrategy($responseFactory);
 $router   = (new League\Route\Router)->setStrategy($strategy);