TASK: Adjust deprecation notices and introduce routingArguments for N…

…odeUri

Neos.Fusion/Classes/FusionObjects/ActionUriImplementation.php

@@ -22,20 +22,6 @@
 /**
  * A Fusion ActionUri object
  *
- * The following Fusion properties are evaluated:
- *  * package
- *  * subpackage
- *  * controller
- *  * action
- *  * arguments
- *  * format
- *  * section
- *  * additionalParams
- *  * addQueryString
- *  * argumentsToBeExcludedFromQueryString
- *  * absolute
- *  * request
- *
  * See respective getters for descriptions
  */
 class ActionUriImplementation extends AbstractFusionObject
@@ -89,26 +75,40 @@ public function getAction(): ?string
     }
 
     /**
-     * Controller arguments that are to be handled by the router
+     * Option to set custom routing arguments
      *
-     * @return array
+     * Please do not use this functionality to append query parameters and use 'queryParameters' instead:
+     *
+     *   Neos.Fusion:ActionUri {
+     *     queryParameters = ${{'q':'search term'}}
+     *   }
+     *
+     * Appending query parameters via the use of exceeding routing arguments relies
+     * on `appendExceedingArguments` internally which is discouraged to leverage.
+     *
+     * But in case you meant to use routing arguments for advanced uri building,
+     * you can leverage this low level option.
+     *
+     * Be aware in order for the routing framework to match and resolve the arguments,
+     * your have to define a custom route in Routes.yaml
+     *
+     * @return array<string, mixed>
      */
     public function getRoutingArguments(): array
     {
-        $routingArguments = $this->fusionValue('routingArguments');
-        return is_array($routingArguments) ? $routingArguments: [];
+        return $this->fusionValue('routingArguments') ?: [];
     }
 
     /**
      * Controller arguments
      *
      * @return array|null
-     * @deprecated to be removed with Neos 9
+     * @deprecated with Neos 8.4 please use routingArguments or queryParameters instead
      */
     public function getArguments(): ?array
     {
         $arguments = $this->fusionValue('arguments');
-        return is_array($arguments) ? $arguments: [];
+        return is_array($arguments) ? $arguments : [];
     }
 
     /**
@@ -135,7 +135,7 @@ public function getSection(): ?string
      * Additional query parameters that won't be prefixed like $arguments (overrule $arguments)
      *
      * @return array|null
-     * @deprecated to be removed with Neos 9
+     * @deprecated with Neos 8.4 please use routingArguments or queryParameters instead
      */
     public function getAdditionalParams(): ?array
     {
@@ -149,8 +149,7 @@ public function getAdditionalParams(): ?array
      */
     public function getQueryParameters(): array
     {
-        $queryParameters = $this->fusionValue('queryParameters');
-        return is_array($queryParameters) ? $queryParameters: [];
+        return $this->fusionValue('queryParameters') ?: [];
     }
 
     /**
@@ -240,7 +239,7 @@ public function evaluate()
             }
             $uriString = $uriBuilder->uriFor(
                 $this->getAction(),
-                $routingArguments ?: $arguments ?: [],
+                $routingArguments ?: $arguments,
                 $this->getController(),
                 $this->getPackage(),
                 $this->getSubpackage()

Neos.Neos/Classes/Fusion/NodeUriImplementation.php

@@ -15,6 +15,7 @@
 use Neos\Flow\Annotations as Flow;
 use Neos\Flow\Log\ThrowableStorageInterface;
 use Neos\Flow\Log\Utility\LogEnvironment;
+use Neos\Fusion\Exception\RuntimeException;
 use Neos\Neos\Service\LinkingService;
 use Neos\Fusion\FusionObjects\AbstractFusionObject;
 use Neos\Neos\Exception as NeosException;
@@ -92,21 +93,48 @@ public function getSection()
      * Additional query parameters that won't be prefixed like $arguments (overrule $arguments)
      *
      * @return array
-     * @deprecated To be removed with Neos 9
      */
-    public function getAdditionalParams()
+    public function getQueryParameters(): array
     {
-        return array_merge($this->fusionValue('additionalParams'), $this->fusionValue('arguments'));
+        return $this->fusionValue('queryParameters') ?: [];
     }
 
     /**
-     * Additional query parameters that won't be prefixed like $arguments (overrule $arguments)
+     * Option to set custom routing arguments
+     *
+     * Please do not use this functionality to append query parameters and use 'queryParameters' instead:
      *
-     * @return array|null
+     *   Neos.Neos:NodeUri {
+     *     queryParameters = ${{'q':'search term'}}
+     *   }
+     *
+     * Appending query parameters via the use of exceeding routing arguments relies
+     * on `appendExceedingArguments` internally which is discouraged to leverage.
+     *
+     * But in case you meant to use routing arguments for advanced uri building,
+     * you can leverage this low level option.
+     *
+     * Be aware in order for the routing framework to match and resolve the arguments,
+     * your have to define a custom route in Routes.yaml
+     *
+     * @return array<string, mixed>
      */
-    public function getQueryParameters(): ?array
+    public function getRoutingArguments(): array
     {
-        return $this->fusionValue('queryParameters');
+        return $this->fusionValue('routingArguments') ?: [];
+    }
+
+    /**
+     * Legacy notation for routing arguments.
+     *
+     * @return array
+     * @deprecated additionalParams and its alias arguments are deprecated with Neos 8.4. Please use queryParameters or routingArguments instead.
+     * @see getQueryParameters
+     * @see getRoutingArguments
+     */
+    public function getAdditionalParams()
+    {
+        return array_merge($this->fusionValue('additionalParams'), $this->fusionValue('arguments'));
     }
 
     /**
@@ -168,14 +196,19 @@ public function evaluate()
             throw new NeosException(sprintf('Could not find a node instance in Fusion context with name "%s" and no node instance was given to the node argument. Set a node instance in the Fusion context or pass a node object to resolve the URI.', $baseNodeName), 1373100400);
         }
 
+        $routingArguments = $this->getRoutingArguments();
+        $legacyRoutingArguments = $this->getAdditionalParams();
+        if ($routingArguments && $legacyRoutingArguments) {
+            throw new RuntimeException('Neos.Neos:NodeUri does not allow to combine the legacy options "arguments", "additionalParams" with "routingArguments"', 1665431866);
+        }
         try {
             $uriString = $this->linkingService->createNodeUri(
                 $this->runtime->getControllerContext(),
                 $this->getNode(),
                 $baseNode,
                 $this->getFormat(),
                 $this->isAbsolute(),
-                $this->getAdditionalParams(),
+                $routingArguments ?: $legacyRoutingArguments,
                 $this->getSection(),
                 $this->getAddQueryString(),
                 $this->getArgumentsToBeExcludedFromQueryString()