Fix docblocks and better IDE and static analyzer discoverery.

src/Collection/CollectionInterface.php

@@ -21,6 +21,8 @@
  * Describes the methods a Collection should implement. A collection is an immutable
  * list of elements exposing a number of traversing and extracting method for
  * generating other collections.
+ *
+ * @method \Cake\Collection\CollectionInterface cartesianProduct(callable $operation = null, callable $filter = null)
  */
 interface CollectionInterface extends Iterator, JsonSerializable
 {

src/Collection/CollectionTrait.php

@@ -283,10 +283,12 @@ public function countBy($callback)
         $callback = $this->_propertyExtractor($callback);
 
         $mapper = function ($value, $key, $mr) use ($callback) {
+            /** @var \Cake\Collection\Iterator\MapReduce $mr */
             $mr->emitIntermediate($value, $callback($value));
         };
 
         $reducer = function ($values, $key, $mr) {
+            /** @var \Cake\Collection\Iterator\MapReduce $mr */
             $mr->emit(count($values), $key);
         };
 
@@ -558,6 +560,7 @@ public function combine($keyPath, $valuePath, $groupPath = null)
         ];
 
         $mapper = function ($value, $key, $mapReduce) use ($options) {
+            /** @var \Cake\Collection\Iterator\MapReduce $mapReduce */
             $rowKey = $options['keyPath'];
             $rowVal = $options['valuePath'];
 
@@ -579,6 +582,7 @@ public function combine($keyPath, $valuePath, $groupPath = null)
             foreach ($values as $value) {
                 $result += $value;
             }
+            /** @var \Cake\Collection\Iterator\MapReduce $mapReduce */
             $mapReduce->emit($result, $key);
         };
 
@@ -600,6 +604,7 @@ public function nest($idPath, $parentPath, $nestingKey = 'children')
             $id = $idPath($row, $key);
             $parentId = $parentPath($row, $key);
             $parents[$id] =& $row;
+            /** @var \Cake\Collection\Iterator\MapReduce $mapReduce */
             $mapReduce->emitIntermediate($id, $parentId);
         };
 
@@ -612,6 +617,7 @@ public function nest($idPath, $parentPath, $nestingKey = 'children')
             if (empty($key) || !isset($parents[$key])) {
                 foreach ($values as $id) {
                     $parents[$id] = $isObject ? $parents[$id] : new ArrayIterator($parents[$id], 1);
+                    /** @var \Cake\Collection\Iterator\MapReduce $mapReduce */
                     $mapReduce->emit($parents[$id]);
                 }
 
@@ -627,6 +633,7 @@ public function nest($idPath, $parentPath, $nestingKey = 'children')
 
         return (new Collection(new MapReduce($this->unwrap(), $mapper, $reducer)))
             ->map(function ($value) use (&$isObject) {
+                /** @var \ArrayIterator $value */
                 return $isObject ? $value : $value->getArrayCopy();
             });
     }
@@ -885,9 +892,10 @@ public function _unwrap()
     }
 
     /**
-     * {@inheritDoc}
-     *
+     * @param callable|null $operation
+     * @param callable|null $filter
      * @return \Cake\Collection\CollectionInterface
+     * @throws \LogicException
      */
     public function cartesianProduct(callable $operation = null, callable $filter = null)
     {
@@ -941,6 +949,7 @@ public function cartesianProduct(callable $operation = null, callable $filter =
      * {@inheritDoc}
      *
      * @return \Cake\Collection\CollectionInterface
+     * @throws \LogicException
      */
     public function transpose()
     {

src/Collection/Iterator/FilterIterator.php

@@ -43,7 +43,7 @@ class FilterIterator extends Collection
      * in the current iteration, the key of the element and the passed $items iterator
      * as arguments, in that order.
      *
-     * @param \Iterator $items The items to be filtered.
+     * @param \Iterator|\Traversable|array $items The items to be filtered.
      * @param callable $callback Callback.
      */
     public function __construct($items, callable $callback)

src/Routing/Router.php

@@ -206,6 +206,7 @@ public static function connect($route, $defaults = [], $options = [])
     {
         static::$initialized = true;
         static::scope('/', function ($routes) use ($route, $defaults, $options) {
+            /** @var \Cake\Routing\RouteBuilder $routes */
             $routes->connect($route, $defaults, $options);
         });
     }
@@ -216,7 +217,7 @@ public static function connect($route, $defaults = [], $options = [])
      * Compatibility proxy to \Cake\Routing\RouteBuilder::redirect() in the `/` scope.
      *
      * @param string $route A string describing the template of the route
-     * @param array $url A URL to redirect to. Can be a string or a Cake array-based URL
+     * @param array|string $url A URL to redirect to. Can be a string or a Cake array-based URL
      * @param array $options An array matching the named elements in the route to regular expressions which that
      *   element should match. Also contains additional parameters such as which routed parameters should be
      *   shifted into the passed arguments. As well as supplying patterns for routing parameters.
@@ -313,6 +314,7 @@ public static function mapResources($controller, $options = [])
             }
 
             $callback = function ($routes) use ($name, $options) {
+                /** @var \Cake\Routing\RouteBuilder $routes */
                 $routes->resources($name, $options);
             };
 

tests/TestCase/Controller/Component/AuthComponentTest.php

@@ -22,6 +22,7 @@
 use Cake\Event\EventManager;
 use Cake\Http\Response;
 use Cake\Http\ServerRequest;
+use Cake\Routing\RouteBuilder;
 use Cake\Routing\Router;
 use Cake\Routing\Route\InflectedRoute;
 use Cake\TestSuite\TestCase;
@@ -61,7 +62,7 @@ public function setUp()
         Security::setSalt('YJfIxfs2guVoUubWDYhG93b0qyJfIxfs2guwvniR2G0FgaC9mi');
         static::setAppNamespace();
 
-        Router::scope('/', function ($routes) {
+        Router::scope('/', function (RouteBuilder $routes) {
             $routes->fallbacks(InflectedRoute::class);
         });
 
@@ -1112,10 +1113,10 @@ public function testAdminRoute()
     {
         $event = new Event('Controller.startup', $this->Controller);
         Router::reload();
-        Router::prefix('admin', function ($routes) {
+        Router::prefix('admin', function (RouteBuilder $routes) {
             $routes->fallbacks(InflectedRoute::class);
         });
-        Router::scope('/', function ($routes) {
+        Router::scope('/', function (RouteBuilder $routes) {
             $routes->fallbacks(InflectedRoute::class);
         });
         $this->Controller->request = new ServerRequest([
@@ -1211,10 +1212,10 @@ public function testLoginActionRedirect()
     {
         $event = new Event('Controller.startup', $this->Controller);
         Router::reload();
-        Router::prefix('admin', function ($routes) {
+        Router::prefix('admin', function (RouteBuilder $routes) {
             $routes->fallbacks(InflectedRoute::class);
         });
-        Router::scope('/', function ($routes) {
+        Router::scope('/', function (RouteBuilder $routes) {
             $routes->fallbacks(InflectedRoute::class);
         });
 

tests/TestCase/ORM/Behavior/TranslateBehaviorTest.php

@@ -15,6 +15,7 @@
 namespace Cake\Test\TestCase\ORM\Behavior;
 
 use Cake\Collection\Collection;
+use Cake\Datasource\EntityInterface;
 use Cake\I18n\I18n;
 use Cake\ORM\Behavior\Translate\TranslateTrait;
 use Cake\ORM\Entity;
@@ -67,14 +68,14 @@ public function tearDown()
      */
     protected function _extractTranslations($data)
     {
-        return (new Collection($data))->map(function ($row) {
+        return (new Collection($data))->map(function (EntityInterface $row) {
             $translations = $row->get('_translations');
             if (!$translations) {
                 return [];
             }
 
-            return array_map(function ($t) {
-                return $t->toArray();
+            return array_map(function (EntityInterface $entity) {
+                return $entity->toArray();
             }, $translations);
         });
     }

tests/TestCase/Routing/Middleware/RoutingMiddlewareTest.php

@@ -23,6 +23,7 @@
 use TestApp\Application;
 use TestApp\Middleware\DumbMiddleware;
 use Zend\Diactoros\Response;
+use Zend\Diactoros\ServerRequest;
 use Zend\Diactoros\ServerRequestFactory;
 
 /**
@@ -52,7 +53,7 @@ public function setUp()
      */
     public function testRedirectResponse()
     {
-        Router::scope('/', function ($routes) {
+        Router::scope('/', function (RouteBuilder $routes) {
             $routes->redirect('/testpath', '/pages');
         });
         $request = ServerRequestFactory::fromGlobals(['REQUEST_URI' => '/testpath']);
@@ -75,7 +76,7 @@ public function testRedirectResponse()
      */
     public function testRedirectResponseWithHeaders()
     {
-        Router::scope('/', function ($routes) {
+        Router::scope('/', function (RouteBuilder $routes) {
             $routes->redirect('/testpath', '/pages');
         });
         $request = ServerRequestFactory::fromGlobals(['REQUEST_URI' => '/testpath']);
@@ -99,7 +100,7 @@ public function testRouterSetParams()
     {
         $request = ServerRequestFactory::fromGlobals(['REQUEST_URI' => '/articles']);
         $response = new Response();
-        $next = function ($req, $res) {
+        $next = function (ServerRequest $req, $res) {
             $expected = [
                 'controller' => 'Articles',
                 'action' => 'index',
@@ -123,7 +124,7 @@ public function testPreservingExistingParams()
         $request = ServerRequestFactory::fromGlobals(['REQUEST_URI' => '/articles']);
         $request = $request->withAttribute('params', ['_csrfToken' => 'i-am-groot']);
         $response = new Response();
-        $next = function ($req, $res) {
+        $next = function (ServerRequest $req, $res) {
             $expected = [
                 'controller' => 'Articles',
                 'action' => 'index',
@@ -150,7 +151,7 @@ public function testRoutesHookInvokedOnApp()
 
         $request = ServerRequestFactory::fromGlobals(['REQUEST_URI' => '/app/articles']);
         $response = new Response();
-        $next = function ($req, $res) {
+        $next = function (ServerRequest $req, $res) {
             $expected = [
                 'controller' => 'Articles',
                 'action' => 'index',
@@ -204,7 +205,7 @@ public function testRouterNoopOnController()
         $request = ServerRequestFactory::fromGlobals(['REQUEST_URI' => '/articles']);
         $request = $request->withAttribute('params', ['controller' => 'Articles']);
         $response = new Response();
-        $next = function ($req, $res) {
+        $next = function (ServerRequest $req, $res) {
             $this->assertEquals(['controller' => 'Articles'], $req->getAttribute('params'));
         };
         $middleware = new RoutingMiddleware($this->app());
@@ -247,7 +248,7 @@ public function testFakedRequestMethodParsed()
             ['_method' => 'PATCH']
         );
         $response = new Response();
-        $next = function ($req, $res) {
+        $next = function (ServerRequest $req, $res) {
             $expected = [
                 'controller' => 'Articles',
                 'action' => 'index',
@@ -270,7 +271,7 @@ public function testFakedRequestMethodParsed()
      */
     public function testInvokeScopedMiddleware()
     {
-        Router::scope('/api', function ($routes) {
+        Router::scope('/api', function (RouteBuilder $routes) {
             $routes->registerMiddleware('first', function ($req, $res, $next) {
                 $this->log[] = 'first';
 
@@ -315,7 +316,7 @@ public function testInvokeScopedMiddleware()
      */
     public function testInvokeScopedMiddlewareReturnResponse()
     {
-        Router::scope('/', function ($routes) {
+        Router::scope('/', function (RouteBuilder $routes) {
             $routes->registerMiddleware('first', function ($req, $res, $next) {
                 $this->log[] = 'first';
 
@@ -330,7 +331,7 @@ public function testInvokeScopedMiddlewareReturnResponse()
             $routes->applyMiddleware('first');
             $routes->connect('/', ['controller' => 'Home']);
 
-            $routes->scope('/api', function ($routes) {
+            $routes->scope('/api', function (RouteBuilder $routes) {
                 $routes->applyMiddleware('second');
                 $routes->connect('/articles', ['controller' => 'Articles']);
             });
@@ -358,7 +359,7 @@ public function testInvokeScopedMiddlewareReturnResponse()
      */
     public function testInvokeScopedMiddlewareReturnResponseMainScope()
     {
-        Router::scope('/', function ($routes) {
+        Router::scope('/', function (RouteBuilder $routes) {
             $routes->registerMiddleware('first', function ($req, $res, $next) {
                 $this->log[] = 'first';
 
@@ -373,7 +374,7 @@ public function testInvokeScopedMiddlewareReturnResponseMainScope()
             $routes->applyMiddleware('first');
             $routes->connect('/', ['controller' => 'Home']);
 
-            $routes->scope('/api', function ($routes) {
+            $routes->scope('/api', function (RouteBuilder $routes) {
                 $routes->applyMiddleware('second');
                 $routes->connect('/articles', ['controller' => 'Articles']);
             });
@@ -405,7 +406,7 @@ public function testInvokeScopedMiddlewareReturnResponseMainScope()
      */
     public function testInvokeScopedMiddlewareIsolatedScopes($url, $expected)
     {
-        Router::scope('/', function ($routes) {
+        Router::scope('/', function (RouteBuilder $routes) {
             $routes->registerMiddleware('first', function ($req, $res, $next) {
                 $this->log[] = 'first';
 
@@ -417,12 +418,12 @@ public function testInvokeScopedMiddlewareIsolatedScopes($url, $expected)
                 return $next($req, $res);
             });
 
-            $routes->scope('/api', function ($routes) {
+            $routes->scope('/api', function (RouteBuilder $routes) {
                 $routes->applyMiddleware('first');
                 $routes->connect('/ping', ['controller' => 'Pings']);
             });
 
-            $routes->scope('/api', function ($routes) {
+            $routes->scope('/api', function (RouteBuilder $routes) {
                 $routes->applyMiddleware('second');
                 $routes->connect('/version', ['controller' => 'Version']);
             });

tests/TestCase/Routing/RouteBuilderTest.php

@@ -665,7 +665,7 @@ public function testResourcesNestedInflection()
         $routes->resources(
             'NetworkObjects',
             ['inflect' => 'dasherize'],
-            function ($routes) {
+            function (RouteBuilder $routes) {
                 $routes->resources('Attributes');
             }
         );
@@ -721,7 +721,7 @@ public function testResourcesMappings()
      */
     public function testResourcesInScope()
     {
-        Router::scope('/api', ['prefix' => 'api'], function ($routes) {
+        Router::scope('/api', ['prefix' => 'api'], function (RouteBuilder $routes) {
             $routes->setExtensions(['json']);
             $routes->resources('Articles');
         });
@@ -873,7 +873,7 @@ public function testResourcesActions()
     public function testResourcesNested()
     {
         $routes = new RouteBuilder($this->collection, '/api', ['prefix' => 'api']);
-        $routes->resources('Articles', function ($routes) {
+        $routes->resources('Articles', function (RouteBuilder $routes) {
             $this->assertEquals('/api/articles/', $routes->path());
             $this->assertEquals(['prefix' => 'api'], $routes->params());
 
@@ -938,7 +938,7 @@ public function testDefaultRouteClassFallbacks()
     public function testScope()
     {
         $routes = new RouteBuilder($this->collection, '/api', ['prefix' => 'api']);
-        $routes->scope('/v1', ['version' => 1], function ($routes) {
+        $routes->scope('/v1', ['version' => 1], function (RouteBuilder $routes) {
             $this->assertEquals('/api/v1', $routes->path());
             $this->assertEquals(['prefix' => 'api', 'version' => 1], $routes->params());
         });
@@ -952,7 +952,7 @@ public function testScope()
     public function testScopeWithAction()
     {
         $routes = new RouteBuilder($this->collection, '/api', ['prefix' => 'api']);
-        $routes->scope('/prices', ['controller' => 'Prices', 'action' => 'view'], function ($routes) {
+        $routes->scope('/prices', ['controller' => 'Prices', 'action' => 'view'], function (RouteBuilder $routes) {
             $routes->connect('/shared', ['shared' => true]);
             $routes->get('/exclusive', ['exclusive' => true]);
         });
@@ -978,7 +978,7 @@ public function testScopeInheritMiddleware()
             ['prefix' => 'api'],
             ['middleware' => ['auth']]
         );
-        $routes->scope('/v1', function ($routes) {
+        $routes->scope('/v1', function (RouteBuilder $routes) {
             $this->assertAttributeEquals(['auth'], 'middleware', $routes, 'Should inherit middleware');
             $this->assertEquals('/api/v1', $routes->path());
             $this->assertEquals(['prefix' => 'api'], $routes->params());
@@ -993,7 +993,7 @@ public function testScopeInheritMiddleware()
     public function testNamePrefixes()
     {
         $routes = new RouteBuilder($this->collection, '/api', [], ['namePrefix' => 'api:']);
-        $routes->scope('/v1', ['version' => 1, '_namePrefix' => 'v1:'], function ($routes) {
+        $routes->scope('/v1', ['version' => 1, '_namePrefix' => 'v1:'], function (RouteBuilder $routes) {
             $this->assertEquals('api:v1:', $routes->namePrefix());
             $routes->connect('/ping', ['controller' => 'Pings'], ['_name' => 'ping']);
 
@@ -1215,7 +1215,7 @@ public function testHttpMethodsStringTarget($method)
     public function testHttpMethodIntegration()
     {
         $routes = new RouteBuilder($this->collection, '/');
-        $routes->scope('/', function ($routes) {
+        $routes->scope('/', function (RouteBuilder $routes) {
             $routes->get('/faq/:page', ['controller' => 'Pages', 'action' => 'faq'], 'faq')
                 ->setPatterns(['page' => '[a-z0-9_]+'])
                 ->setHost('docs.example.com');