Documented UrlHelper and RouterInterface::generateUri changes

Author: weierophinney

doc/book/features/helpers/url-helper.md

@@ -64,6 +64,12 @@ Each method will raise an exception if:
   represents a matching failure.
 - The given `$routeName` is not defined in the router.
 
+> ### Signature changes
+>
+> The signature listed above is current as of version 3.0.0 of
+> zendframework/zend-expressive-helpers. Prior to that version, the helper only
+> accepted the route name and route parameters.
+
 ## Creating an instance
 
 In order to use the helper, you will need to instantiate it with the current

doc/book/features/router/interface.md

@@ -76,6 +76,21 @@ Implementors should also read the following sections detailing the `Route` and
 `RouteResult` classes, to ensure that their implementations interoperate
 correctly.
 
+> ### generateUri() signature change in 2.0
+>
+> Prior to zendframework/zend-expressive-router 2.0.0, the signature of
+> `generateUri()` was:
+>
+> ```php
+> public function generateUri(
+>     string $name,
+>     array $substitutions = []
+> ) : string
+> ```
+> 
+> If you are targeting that version, you may still provide the `$options`
+> argument, but it will not be invoked.
+
 ## Routes
 
 Routes are defined via `Zend\Expressive\Router\Route`, and aggregate the

doc/book/reference/migration/to-v2.md

@@ -738,3 +738,58 @@ entries for each will be injected into your generated pipeline.
 
 Please see the [chapter on the implicit methods middleware](../../features/middleware/implicit-methods-middleware.md)
 for more information on each.
+
+## Router interface changes
+
+Expressive 2.0 uses zendframework/zend-expressive-router 2.1+. Version 2.0 of
+that package introduced a change to the `Zend\Expressive\Router\RouterInterface::generateUri()`
+method; it now accepts an additional, optional, third argument, `array $options = []`,
+which can be used to pass router-specific options when generating a URI. As an
+example, the implementation that uses zendframework/zend-router might use these
+options to pass a translator instance in order to translate a path segment to
+the currently selected locale.
+
+For consumers, his represents no backwards-incompatible change; consumers may
+opt-in to the new argument at will. For those implementing the interface,
+upgrading will require updating your router implementation's signature to match
+the new interface:
+
+```php
+public function generateUri(
+    string $name,
+    array $substitutions = [],
+    array $options = []
+) : string
+```
+
+## URL helper changes
+
+Expressive 2.0 uses zendframework/zend-expressive-helpers version 3.0+. This new
+version updates the signature of the `Zend\Expressive\Helper\UrlHelper` from:
+
+```php
+function (
+    $routeName,
+    array $routeParams = []
+) : string
+```
+
+to:
+
+```php
+function (
+    $routeName,
+    array $routeParams = [],
+    $queryParams = [],
+    $fragmentIdentifier = null,
+    array $options = []
+) : string
+```
+
+For consumers, this should represent a widening of features, and will not
+require any changes, unless you wish to opt-in to the new arguments. See the
+[UrlHelper documentation](../../features/helpers/url-helper.md) for information
+on each argument.
+
+For any users who were _extending_ the class, you will need to update your
+extension accordingly.