Merge pull request #8505 from kenjis/fix-phpdocs

docs: fix PHPDocs
codeigniter4 · Feb 4, 2024 · 8fbe586 · 8fbe586
2 parents d6d571b + 267d6c0
commit 8fbe586
Show file tree

Hide file tree

Showing 9 changed files with 37 additions and 140 deletions.
diff --git a/phpstan-baseline.php b/phpstan-baseline.php
@@ -2491,11 +2491,6 @@
 	'count' => 1,
 	'path' => __DIR__ . '/system/Router/AutoRouter.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Property CodeIgniter\\\\Router\\\\AutoRouter\\:\\:\\$cliRoutes type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/AutoRouter.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Short ternary operator is not allowed\\. Use null coalesce operator if applicable or consider using long ternary\\.$#',
 	'count' => 1,
@@ -2516,81 +2511,16 @@
 	'count' => 6,
 	'path' => __DIR__ . '/system/Router/RouteCollection.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:add\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:cli\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:create\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:delete\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:environment\\(\\) has parameter \\$callback with no signature specified for Closure\\.$#',
 	'count' => 1,
 	'path' => __DIR__ . '/system/Router/RouteCollection.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:get\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:get404Override\\(\\) return type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:getControllerName\\(\\) has parameter \\$handler with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:group\\(\\) has parameter \\$params with no signature specified for callable\\.$#',
 	'count' => 1,
 	'path' => __DIR__ . '/system/Router/RouteCollection.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:head\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:match\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:options\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:patch\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:post\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:put\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollection\\:\\:set404Override\\(\\) has parameter \\$callable with no signature specified for callable\\.$#',
 	'count' => 1,
@@ -2611,21 +2541,6 @@
 	'count' => 1,
 	'path' => __DIR__ . '/system/Router/RouteCollection.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Property CodeIgniter\\\\Router\\\\RouteCollection\\:\\:\\$override404 type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollection.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollectionInterface\\:\\:add\\(\\) has parameter \\$to with no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollectionInterface.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollectionInterface\\:\\:get404Override\\(\\) return type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouteCollectionInterface.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method CodeIgniter\\\\Router\\\\RouteCollectionInterface\\:\\:set404Override\\(\\) has parameter \\$callable with no signature specified for callable\\.$#',
 	'count' => 1,
@@ -2681,41 +2596,16 @@
 	'count' => 1,
 	'path' => __DIR__ . '/system/Router/Router.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\Router\\:\\:controllerName\\(\\) return type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/Router.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method CodeIgniter\\\\Router\\\\Router\\:\\:get404Override\\(\\) has no return type specified\\.$#',
 	'count' => 1,
 	'path' => __DIR__ . '/system/Router/Router.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\Router\\:\\:handle\\(\\) return type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/Router.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method CodeIgniter\\\\Router\\\\Router\\:\\:setMatchedRoute\\(\\) has parameter \\$handler with no signature specified for callable\\.$#',
 	'count' => 1,
 	'path' => __DIR__ . '/system/Router/Router.php',
 ];
-$ignoreErrors[] = [
-	'message' => '#^Property CodeIgniter\\\\Router\\\\Router\\:\\:\\$controller type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/Router.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouterInterface\\:\\:controllerName\\(\\) return type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouterInterface.php',
-];
-$ignoreErrors[] = [
-	'message' => '#^Method CodeIgniter\\\\Router\\\\RouterInterface\\:\\:handle\\(\\) return type has no signature specified for Closure\\.$#',
-	'count' => 1,
-	'path' => __DIR__ . '/system/Router/RouterInterface.php',
-];
 $ignoreErrors[] = [
 	'message' => '#^Method CodeIgniter\\\\Session\\\\Exceptions\\\\SessionException\\:\\:forEmptySavepath\\(\\) has no return type specified\\.$#',
 	'count' => 1,

diff --git a/system/Database/BaseBuilder.php b/system/Database/BaseBuilder.php
@@ -1968,7 +1968,7 @@ public function upsertBatch($set = null, ?bool $escape = null, int $batchSize =
     /**
      * Generates a platform-specific upsertBatch string from the supplied data
      *
-     * @used-by batchExecute
+     * @used-by batchExecute()
      *
      * @param string                 $table  Protected table name
      * @param list<string>           $keys   QBKeys
@@ -2195,7 +2195,7 @@ public function insertBatch($set = null, ?bool $escape = null, int $batchSize =
     /**
      * Generates a platform-specific insert string from the supplied data.
      *
-     * @used-by batchExecute
+     * @used-by batchExecute()
      *
      * @param string                 $table  Protected table name
      * @param list<string>           $keys   QBKeys
@@ -2563,7 +2563,7 @@ public function updateBatch($set = null, $constraints = null, int $batchSize = 1
     /**
      * Generates a platform-specific batch update string from the supplied data
      *
-     * @used-by batchExecute
+     * @used-by batchExecute()
      *
      * @param string                 $table  Protected table name
      * @param list<string>           $keys   QBKeys
@@ -2825,7 +2825,7 @@ public function deleteBatch($set = null, $constraints = null, int $batchSize = 1
     /**
      * Generates a platform-specific batch update string from the supplied data
      *
-     * @used-by batchExecute
+     * @used-by batchExecute()
      *
      * @param string       $table Protected table name
      * @param list<string> $keys  QBKeys

diff --git a/system/Database/Postgre/Builder.php b/system/Database/Postgre/Builder.php
@@ -315,7 +315,7 @@ public function join(string $table, $cond, string $type = '', ?bool $escape = nu
     /**
      * Generates a platform-specific batch update string from the supplied data
      *
-     * @used-by batchExecute
+     * @used-by batchExecute()
      *
      * @param string                 $table  Protected table name
      * @param list<string>           $keys   QBKeys

diff --git a/system/Email/Email.php b/system/Email/Email.php
@@ -1665,7 +1665,9 @@ protected function unwrapSpecials()
     /**
      * Strip line-breaks via callback
      *
-     * @param string $matches
+     * @used-by unwrapSpecials()
+     *
+     * @param list<string> $matches
      *
      * @return string
      */

diff --git a/system/Router/AutoRouter.php b/system/Router/AutoRouter.php
@@ -13,6 +13,7 @@
 
 use Closure;
 use CodeIgniter\Exceptions\PageNotFoundException;
+use CodeIgniter\HTTP\ResponseInterface;
 
 /**
  * Router for Auto-Routing
@@ -22,7 +23,7 @@ final class AutoRouter implements AutoRouterInterface
     /**
      * List of CLI routes that do not contain '*' routes.
      *
-     * @var array<string, Closure|string> [routeKey => handler]
+     * @var array<string, (Closure(mixed...): (ResponseInterface|string|void))|string> [routeKey => handler]
      */
     private array $cliRoutes;
 

diff --git a/system/Router/RouteCollection.php b/system/Router/RouteCollection.php
@@ -13,6 +13,7 @@
 
 use Closure;
 use CodeIgniter\Autoloader\FileLocator;
+use CodeIgniter\HTTP\ResponseInterface;
 use CodeIgniter\Router\Exceptions\RouterException;
 use Config\App;
 use Config\Modules;
@@ -87,7 +88,7 @@ class RouteCollection implements RouteCollectionInterface
      * A callable that will be shown
      * when the route cannot be matched.
      *
-     * @var Closure|string
+     * @var (Closure(string): (ResponseInterface|string|void))|string
      */
     protected $override404;
 
@@ -497,7 +498,7 @@ public function set404Override($callable = null): RouteCollectionInterface
      * Returns the 404 Override setting, which can be null, a closure
      * or the controller/string.
      *
-     * @return Closure|string|null
+     * @return (Closure(string): (ResponseInterface|string|void))|string|null
      */
     public function get404Override()
     {
@@ -658,7 +659,7 @@ public function map(array $routes = [], ?array $options = null): RouteCollection
      * Example:
      *      $routes->add('news', 'Posts::index');
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function add(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -992,7 +993,7 @@ public function presenter(string $name, ?array $options = null): RouteCollection
      * Example:
      *  $route->match( ['get', 'post'], 'users/(:num)', 'users/$1);
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function match(array $verbs = [], string $from = '', $to = '', ?array $options = null): RouteCollectionInterface
     {
@@ -1012,7 +1013,7 @@ public function match(array $verbs = [], string $from = '', $to = '', ?array $op
     /**
      * Specifies a route that is only available to GET requests.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function get(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -1024,7 +1025,7 @@ public function get(string $from, $to, ?array $options = null): RouteCollectionI
     /**
      * Specifies a route that is only available to POST requests.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function post(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -1036,7 +1037,7 @@ public function post(string $from, $to, ?array $options = null): RouteCollection
     /**
      * Specifies a route that is only available to PUT requests.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function put(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -1048,7 +1049,7 @@ public function put(string $from, $to, ?array $options = null): RouteCollectionI
     /**
      * Specifies a route that is only available to DELETE requests.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function delete(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -1060,7 +1061,7 @@ public function delete(string $from, $to, ?array $options = null): RouteCollecti
     /**
      * Specifies a route that is only available to HEAD requests.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function head(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -1072,7 +1073,7 @@ public function head(string $from, $to, ?array $options = null): RouteCollection
     /**
      * Specifies a route that is only available to PATCH requests.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function patch(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -1084,7 +1085,7 @@ public function patch(string $from, $to, ?array $options = null): RouteCollectio
     /**
      * Specifies a route that is only available to OPTIONS requests.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function options(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -1096,7 +1097,7 @@ public function options(string $from, $to, ?array $options = null): RouteCollect
     /**
      * Specifies a route that is only available to command-line requests.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      */
     public function cli(string $from, $to, ?array $options = null): RouteCollectionInterface
     {
@@ -1416,7 +1417,7 @@ private function replaceLocale(string $route, ?string $locale = null): string
      * the request method(s) that this route will work for. They can be separated
      * by a pipe character "|" if there is more than one.
      *
-     * @param array|Closure|string $to
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to
      *
      * @return void
      */
@@ -1767,7 +1768,7 @@ public function getRegisteredControllers(?string $verb = '*'): array
     }
 
     /**
-     * @param Closure|string $handler Handler
+     * @param (Closure(mixed...): (ResponseInterface|string|void))|string $handler Handler
      *
      * @return string|null Controller classname
      */

diff --git a/system/Router/RouteCollectionInterface.php b/system/Router/RouteCollectionInterface.php
@@ -12,6 +12,7 @@
 namespace CodeIgniter\Router;
 
 use Closure;
+use CodeIgniter\HTTP\ResponseInterface;
 
 /**
  * Interface RouteCollectionInterface
@@ -28,9 +29,9 @@ interface RouteCollectionInterface
     /**
      * Adds a single route to the collection.
      *
-     * @param string               $from    The route path (with placeholders or regex)
-     * @param array|Closure|string $to      The route handler
-     * @param array|null           $options The route options
+     * @param string                                                            $from    The route path (with placeholders or regex)
+     * @param array|(Closure(mixed...): (ResponseInterface|string|void))|string $to      The route handler
+     * @param array|null                                                        $options The route options
      *
      * @return RouteCollectionInterface
      */
@@ -111,7 +112,7 @@ public function set404Override($callable = null): self;
      * Returns the 404 Override setting, which can be null, a closure
      * or the controller/string.
      *
-     * @return Closure|string|null
+     * @return (Closure(string): (ResponseInterface|string|void))|string|null
      */
     public function get404Override();