Move unused arguments to query parameters on URL generation (#260)

CHANGELOG.md

@@ -10,6 +10,8 @@
 - Enh #256: Mark readonly properties (@vjik)
 - Chg #257: Change PHP constraint in `composer.json` to `~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0` (@vjik)
 - Bug #257: Explicitly mark nullable parameters (@vjik)
+- Сhg #247: Change `UrlGeneratorInterface` contract: on URL generation all unused arguments must be moved to query
+  parameters, if query parameter with such name doesn't exist (@vjik)
 
 ## 3.1.0 February 20, 2024
 

UPGRADE.md

@@ -5,12 +5,14 @@ These notes highlight changes that could break your application when you upgrade
 
 ## 4.0.0
 
+### `Route`, `Group` and `MatchingResult` changes
+
 In this release classes `Route`, `Group` and `MatchingResult` are made dispatcher-independent. Now you don't can inject
 own middleware dispatcher to group or to route.
 
 The following backward incompatible changes have been made.
 
-### `Route`
+#### `Route`
 
 - Removed parameter `$dispatcher` from `Route` creating methods: `get()`, `post()`, `put()`, `delete()`, `patch()`,
   `head()`, `options()`, `methods()`.
@@ -19,7 +21,7 @@ The following backward incompatible changes have been made.
   - removed elements `dispatcherWithMiddlewares` and `hasDispatcher`;
   - added element `enabledMiddlewares`.
 
-### `Group`
+#### `Group`
 
 - Removed parameter `$dispatcher` from `Group::create()` method.
 - Removed method `Group::withDispatcher()`.
@@ -28,7 +30,12 @@ The following backward incompatible changes have been made.
   - key `items` renamed to `routes`;
   - key `middlewareDefinitions` renamed to `enabledMiddlewares`.
 
-### `MatchingResult`
+#### `MatchingResult`
 
 - Removed `MatchingResult` implementation from `MiddlewareInterface`, so it is no longer middleware.
 - Removed method `MatchingResult::process()`.
+
+### `UrlGeneratorInterface` changes
+
+Contract is changed: on URL generation all unused arguments must be moved to query parameters, if query parameter with 
+such name doesn't exist. You should change your interface implementations accordingly.

src/UrlGeneratorInterface.php

@@ -17,7 +17,8 @@ interface UrlGeneratorInterface
      * Generates URL from named route, arguments, and query parameters.
      *
      * @param string $name Name of the route.
-     * @param array $arguments Argument-value set.
+     * @param array $arguments Argument-value set. Unused arguments will be moved to query parameters, if query
+     * parameter with such name doesn't exist.
      * @param array $queryParameters Parameter-value set.
      *
      * @throws RouteNotFoundException In case there is no route with the name specified.
@@ -32,7 +33,8 @@ public function generate(string $name, array $arguments = [], array $queryParame
      * Generates absolute URL from named route, arguments, and query parameters.
      *
      * @param string $name Name of the route.
-     * @param array $arguments Argument-value set.
+     * @param array $arguments Argument-value set. Unused arguments will be moved to query parameters, if query
+     * parameter with such name doesn't exist.
      * @param array $queryParameters Parameter-value set.
      * @param string|null $scheme Host scheme.
      * @param string|null $host Host for manual setup.
@@ -54,7 +56,8 @@ public function generateAbsolute(
     /**
      * Generate URL from the current route replacing some of its arguments with values specified.
      *
-     * @param array $replacedArguments New argument values indexed by replaced argument names.
+     * @param array $replacedArguments New argument values indexed by replaced argument names. Unused arguments will be
+     * moved to query parameters, if query parameter with such name doesn't exist.
      * @param array $queryParameters Parameter-value set.
      * @param string|null $fallbackRouteName Name of a route that should be used if current route.
      * can not be determined.