[TASK] Streamline routing related phpDoc comments & annotations

Resolves: #94148 Releases: master, 10.4, 9.5 Change-Id: If1378f2d471f18099b55b05a84dc81adc247bc69 Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/69160 Tested-by: core-ci <typo3@b13.com> Tested-by: Benni Mack <benni@typo3.org> Tested-by: Oliver Hader <oliver.hader@typo3.org> Reviewed-by: Benni Mack <benni@typo3.org> Reviewed-by: Oliver Hader <oliver.hader@typo3.org>
TYPO3 · May 17, 2021 · 3cf15c5 · 3cf15c5
1 parent 3b0fffb
commit 3cf15c5
Show file tree

Hide file tree

Showing 5 changed files with 40 additions and 27 deletions.
diff --git a/typo3/sysext/core/Classes/Routing/Enhancer/PluginEnhancer.php b/typo3/sysext/core/Classes/Routing/Enhancer/PluginEnhancer.php
@@ -80,7 +80,7 @@ public function buildResult(Route $route, array $results, array $remainingQueryP
         // dynamic arguments, that don't have a static mapper
         $dynamicArguments = $variableProcessor
             ->inflateNamespaceParameters($dynamicCandidates, $this->namespace);
-        // static arguments, that don't appear in dynamic arguments
+        // route arguments, that don't appear in dynamic arguments
         $staticArguments = ArrayUtility::arrayDiffKeyRecursive($routeArguments, $dynamicArguments);
 
         $page = $route->getOption('_page');

diff --git a/typo3/sysext/core/Classes/Routing/Enhancer/SimpleEnhancer.php b/typo3/sysext/core/Classes/Routing/Enhancer/SimpleEnhancer.php
@@ -64,11 +64,11 @@ public function buildResult(Route $route, array $results, array $remainingQueryP
         $dynamicCandidates = array_diff_key($parameters, $staticMappers);
 
         // all route arguments
-        $routeArguments = $this->getVariableProcessor()->inflateParameters($parameters, $route->getArguments());
+        $routeArguments = $variableProcessor->inflateParameters($parameters, $route->getArguments());
         // dynamic arguments, that don't have a static mapper
         $dynamicArguments = $variableProcessor
             ->inflateNamespaceParameters($dynamicCandidates, '');
-        // static arguments, that don't appear in dynamic arguments
+        // route arguments, that don't appear in dynamic arguments
         $staticArguments = ArrayUtility::arrayDiffKeyRecursive($routeArguments, $dynamicArguments);
 
         $page = $route->getOption('_page');

diff --git a/typo3/sysext/core/Classes/Routing/PageArguments.php b/typo3/sysext/core/Classes/Routing/PageArguments.php
@@ -35,27 +35,40 @@ class PageArguments implements RouteResultInterface
     protected $pageType;
 
     /**
-     * @var array
+     * All (merged) arguments of this URI (routeArguments + dynamicArguments)
+     *
+     * @var array<string, string|array>
      */
     protected $arguments;
 
     /**
-     * @var array
+     * Route arguments mapped by static mappers
+     * "static" means the provided values in a URI maps to a finite number of values
+     * (routeArguments - "arguments mapped by non static mapper")
+     *
+     * @var array<string, string|array>
      */
     protected $staticArguments;
 
     /**
-     * @var array
+     * Route arguments, that have an infinite number of possible values
+     * AND query string arguments. These arguments require a cHash.
+     *
+     * @var array<string, string|array>
      */
     protected $dynamicArguments;
 
     /**
-     * @var array
+     * Arguments defined in and mapped by a route enhancer
+     *
+     * @var array<string, string|array>
      */
     protected $routeArguments;
 
     /**
-     * @var array
+     * Query arguments in the generated URI
+     *
+     * @var array<string, string|array>
      */
     protected $queryArguments = [];
 
@@ -93,7 +106,7 @@ public function areDirty(): bool
     }
 
     /**
-     * @return array
+     * @return array<string, string|array>
      */
     public function getRouteArguments(): array
     {
@@ -118,47 +131,47 @@ public function getPageType(): string
 
     /**
      * @param string $name
-     * @return mixed|null
+     * @return string|array<string, string|array>|null
      */
     public function get(string $name)
     {
         return $this->arguments[$name] ?? null;
     }
 
     /**
-     * @return array
+     * @return array<string, string|array>
      */
     public function getArguments(): array
     {
         return $this->arguments;
     }
 
     /**
-     * @return array
+     * @return array<string, string|array>
      */
     public function getStaticArguments(): array
     {
         return $this->staticArguments;
     }
 
     /**
-     * @return array
+     * @return array<string, string|array>
      */
     public function getDynamicArguments(): array
     {
         return $this->dynamicArguments;
     }
 
     /**
-     * @return array
+     * @return array<string, string|array>
      */
     public function getQueryArguments(): array
     {
         return $this->queryArguments;
     }
 
     /**
-     * @param array $queryArguments
+     * @param array<string, string|array> $queryArguments
      */
     protected function updateQueryArguments(array $queryArguments)
     {
@@ -191,7 +204,7 @@ protected function updateDynamicArguments(): void
     /**
      * Cleans empty array recursively.
      *
-     * @param array $array
+     * @param array<string, string|array> $array
      * @return array
      */
     protected function clean(array $array): array
@@ -213,7 +226,7 @@ protected function clean(array $array): array
     /**
      * Sorts array keys recursively.
      *
-     * @param array $array
+     * @param array<string, string|array> $array
      * @return array
      */
     protected function sort(array $array): array
@@ -226,8 +239,8 @@ protected function sort(array $array): array
     /**
      * Removes keys that are defined in $second from $first recursively.
      *
-     * @param array $first
-     * @param array $second
+     * @param array<string, string|array> $first
+     * @param array<string, string|array> $second
      * @return array
      */
     protected function diff(array $first, array $second): array
@@ -246,7 +259,7 @@ public function offsetExists($offset): bool
 
     /**
      * @param mixed $offset
-     * @return mixed
+     * @return string|array<string, string|array>|null
      */
     public function offsetGet($offset)
     {

diff --git a/...tion/Changelog/10.3/Deprecation-89868-RemoveReqCHashFunctionalityForPlugins.rst b/...tion/Changelog/10.3/Deprecation-89868-RemoveReqCHashFunctionalityForPlugins.rst
@@ -23,7 +23,7 @@ was used to enable the cHash validation for non-cacheable plugins.
 Both plugin systems triggered the method :php:`TypoScriptFrontendController->reqCHash` which
 validated relevant GET parameters. However, the :php:`PageArgumentValidator` PSR-15 middleware now
 always validates the cHash, so a plugin does not need to know about cHash validation anymore and
-therefor does not need to set the option.
+therefore does not need to set the option.
 
 This means the options are not needed anymore, as the validation already happens during the Frontend
 request handling process. The options are removed.

diff --git a/typo3/sysext/frontend/Classes/Middleware/PageArgumentValidator.php b/typo3/sysext/frontend/Classes/Middleware/PageArgumentValidator.php
@@ -96,11 +96,11 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
             return $handler->handle($request);
         }
         // Evaluate the cache hash parameter or dynamic arguments when coming from a Site-based routing
-        $cHash = $pageArguments->getArguments()['cHash'] ?? '';
+        $cHash = (string)($pageArguments->getArguments()['cHash'] ?? '');
         $queryParams = $pageArguments->getDynamicArguments();
-        if ($cHash || !empty($queryParams)) {
+        if ($cHash !== '' || !empty($queryParams)) {
             $relevantParametersForCacheHashArgument = $this->getRelevantParametersForCacheHashCalculation($pageArguments);
-            if ($cHash) {
+            if ($cHash !== '') {
                 if (empty($relevantParametersForCacheHashArgument)) {
                     // cHash was given, but nothing to be calculated, so let's do a redirect to the current page
                     // but without the cHash
@@ -135,7 +135,7 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
      * Filters out the arguments that are necessary for calculating cHash
      *
      * @param PageArguments $pageArguments
-     * @return array
+     * @return array<string, string>
      */
     protected function getRelevantParametersForCacheHashCalculation(PageArguments $pageArguments): array
     {
@@ -149,7 +149,7 @@ protected function getRelevantParametersForCacheHashCalculation(PageArguments $p
      * This is used to cache pages with more parameters than just id and type.
      *
      * @param string $cHash the chash to check
-     * @param array $relevantParameters GET parameters necessary for cHash calculation
+     * @param array<string, string> $relevantParameters GET parameters necessary for cHash calculation
      * @param bool $pageNotFoundOnCacheHashError see $GLOBALS['TYPO3_CONF_VARS']['FE']['pageNotFoundOnCHashError']
      * @return bool if false, then a PageNotFound response is triggered
      */
@@ -174,7 +174,7 @@ protected function evaluateCacheHashParameter(string $cHash, array $relevantPara
      *
      * Should only be called if NO cHash parameter is given.
      *
-     * @param array $dynamicArguments
+     * @param array<string, string|array> $dynamicArguments
      * @param bool $pageNotFoundOnCacheHashError
      * @return bool
      */