Merge pull request #11236 from cakephp/master-ide-comp

Improve doc blocks for IDE understanding.

src/Auth/BaseAuthenticate.php

@@ -22,6 +22,8 @@
 
 /**
  * Base Authentication class with common methods and properties.
+ *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 abstract class BaseAuthenticate implements EventListenerInterface
 {

src/Auth/BaseAuthorize.php

@@ -22,6 +22,7 @@
  * Abstract base authorization adapter for AuthComponent.
  *
  * @see \Cake\Controller\Component\AuthComponent::$authenticate
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 abstract class BaseAuthorize
 {

src/Auth/Storage/SessionStorage.php

@@ -20,6 +20,8 @@
 
 /**
  * Session based persistent storage for authenticated user record.
+ *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 class SessionStorage implements StorageInterface
 {

src/Cache/CacheEngine.php

@@ -19,6 +19,8 @@
 
 /**
  * Storage engine for CakePHP caching
+ *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 abstract class CacheEngine
 {

src/Controller/Component.php

@@ -55,6 +55,7 @@
  *
  * @link https://book.cakephp.org/3.0/en/controllers/components.html
  * @see \Cake\Controller\Controller::$components
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 class Component implements EventListenerInterface
 {

src/Datasource/QueryInterface.php

@@ -19,6 +19,7 @@
  * The basis for every query object
  *
  * @method $this andWhere($conditions, $types = [])
+ * @method $this select($fields = [], $overwrite = false)
  */
 interface QueryInterface
 {
@@ -37,7 +38,7 @@ interface QueryInterface
      *
      * @param string $field The field to alias
      * @param string|null $alias the alias used to prefix the field
-     * @return array
+     * @return string
      */
     public function aliasField($field, $alias = null);
 
@@ -47,7 +48,7 @@ public function aliasField($field, $alias = null);
      *
      * @param array $fields The fields to alias
      * @param string|null $defaultAlias The default alias
-     * @return array
+     * @return string[]
      */
     public function aliasFields($fields, $defaultAlias = null);
 

src/Datasource/QueryTrait.php

@@ -28,7 +28,7 @@ trait QueryTrait
     /**
      * Instance of a table object this query is bound to
      *
-     * @var \Cake\Datasource\RepositoryInterface
+     * @var \Cake\ORM\Table|\Cake\Datasource\RepositoryInterface
      */
     protected $_repository;
 

src/Error/Middleware/ErrorHandlerMiddleware.php

@@ -27,6 +27,8 @@
  *
  * Traps exceptions and converts them into HTML or content-type appropriate
  * error pages using the CakePHP ExceptionRenderer.
+ *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 class ErrorHandlerMiddleware
 {

src/Http/Client.php

@@ -91,6 +91,7 @@
  * specify which authentication strategy you want to use.
  * CakePHP comes with built-in support for basic authentication.
  *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 class Client
 {

src/Log/Engine/BaseLog.php

@@ -21,6 +21,8 @@
 
 /**
  * Base log engine class.
+ *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 abstract class BaseLog extends AbstractLogger
 {

src/Mailer/AbstractTransport.php

@@ -18,6 +18,8 @@
 
 /**
  * Abstract transport for sending email
+ *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 abstract class AbstractTransport
 {

src/Network/Socket.php

@@ -24,6 +24,8 @@
  * CakePHP network socket connection class.
  *
  * Core base class for network communication.
+ *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 class Socket
 {

src/ORM/Association.php

@@ -1192,6 +1192,7 @@ protected function _formatAssociationResults($query, $surrogate, $options)
                 $extracted = new ResultSetDecorator($callable($extracted));
             }
 
+            /* @var \Cake\Collection\CollectionInterface $results */
             return $results->insert($property, $extracted);
         }, Query::PREPEND);
     }

src/ORM/Behavior.php

@@ -109,6 +109,7 @@
  *
  * @see \Cake\ORM\Table::addBehavior()
  * @see \Cake\Event\EventManager
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 class Behavior implements EventListenerInterface
 {

src/ORM/Behavior/CounterCacheBehavior.php

@@ -18,6 +18,7 @@
 use Cake\Event\Event;
 use Cake\ORM\Association;
 use Cake\ORM\Behavior;
+use RuntimeException;
 
 /**
  * CounterCache behavior
@@ -202,6 +203,7 @@ protected function _processAssociations(Event $event, EntityInterface $entity)
      * @param \Cake\ORM\Association $assoc The association object
      * @param array $settings The settings for for counter cache for this association
      * @return void
+     * @throws \RuntimeException If invalid callable is passed.
      */
     protected function _processAssociation(Event $event, EntityInterface $entity, Association $assoc, array $settings)
     {
@@ -227,7 +229,10 @@ protected function _processAssociation(Event $event, EntityInterface $entity, As
                 continue;
             }
 
-            if (!is_string($config) && is_callable($config)) {
+            if (is_callable($config)) {
+                if (is_string($config)) {
+                    throw new RuntimeException('You must not use a string as callable.');
+                }
                 $count = $config($event, $entity, $this->_table, false);
             } else {
                 $count = $this->_getCount($config, $countConditions);
@@ -236,7 +241,10 @@ protected function _processAssociation(Event $event, EntityInterface $entity, As
             $assoc->getTarget()->updateAll([$field => $count], $updateConditions);
 
             if (isset($updateOriginalConditions)) {
-                if (!is_string($config) && is_callable($config)) {
+                if (is_callable($config)) {
+                    if (is_string($config)) {
+                        throw new RuntimeException('You must not use a string as callable.');
+                    }
                     $count = $config($event, $entity, $this->_table, true);
                 } else {
                     $count = $this->_getCount($config, $countOriginalConditions);

src/ORM/Behavior/TranslateBehavior.php

@@ -215,8 +215,10 @@ public function beforeFind(Event $event, Query $query, $options)
 
         $conditions = function ($field, $locale, $query, $select) {
             return function ($q) use ($field, $locale, $query, $select) {
+                /* @var \Cake\Datasource\QueryInterface $q */
                 $q->where([$q->repository()->aliasField('locale') => $locale]);
 
+                /* @var \Cake\ORM\Query $query */
                 if ($query->isAutoFieldsEnabled() ||
                     in_array($field, $select, true) ||
                     in_array($this->_table->aliasField($field), $select, true)
@@ -382,12 +384,13 @@ public function buildMarshalMap($marshaller, $map, $options)
 
         return [
             '_translations' => function ($value, $entity) use ($marshaller, $options) {
+                /* @var \Cake\Datasource\EntityInterface $entity */
                 $translations = $entity->get('_translations');
                 foreach ($this->_config['fields'] as $field) {
                     $options['validate'] = $this->_config['validator'];
                     $errors = [];
                     if (!is_array($value)) {
-                        return;
+                        return null;
                     }
                     foreach ($value as $language => $fields) {
                         if (!isset($translations[$language])) {
@@ -478,12 +481,13 @@ public function findTranslations(Query $query, array $options)
         $targetAlias = $this->_translationTable->getAlias();
 
         return $query
-            ->contain([$targetAlias => function ($q) use ($locales, $targetAlias) {
+            ->contain([$targetAlias => function ($query) use ($locales, $targetAlias) {
                 if ($locales) {
-                    $q->where(["$targetAlias.locale IN" => $locales]);
+                    /* @var \Cake\Datasource\QueryInterface $query */
+                    $query->where(["$targetAlias.locale IN" => $locales]);
                 }
 
-                return $q;
+                return $query;
             }])
             ->formatResults([$this, 'groupTranslations'], $query::PREPEND);
     }
@@ -546,6 +550,7 @@ protected function _rowMapper($results, $locale)
 
             $row['_locale'] = $locale;
             if ($hydrated) {
+                /* @var \Cake\Datasource\EntityInterface $row */
                 $row->clean();
             }
 

src/ORM/Query.php

@@ -65,6 +65,7 @@
  *   with the first rows of the query and each of the items, then the second rows and so on.
  * @method \Cake\Collection\CollectionInterface chunk($size) Groups the results in arrays of $size rows each.
  * @method bool isEmpty() Returns true if this query found no results.
+ * @mixin \Cake\Datasource\QueryTrait
  */
 class Query extends DatabaseQuery implements JsonSerializable, QueryInterface
 {
@@ -423,7 +424,7 @@ public function clearContain()
      * Used to recursively add contained association column types to
      * the query.
      *
-     * @param \Cake\ORM\Table $table The table instance to pluck associations from.
+     * @param \Cake\ORM\Table|\Cake\Datasource\RepositoryInterface $table The table instance to pluck associations from.
      * @param \Cake\Database\TypeMap $typeMap The typemap to check for columns in.
      *   This typemap is indirectly mutated via Cake\ORM\Query::addDefaultTypes()
      * @param array $associations The nested tree of associations to walk.
@@ -998,6 +999,7 @@ public function triggerBeforeFind()
         if (!$this->_beforeFindFired && $this->_type === 'select') {
             $table = $this->repository();
             $this->_beforeFindFired = true;
+            /* @var \Cake\Event\EventDispatcherInterface $table */
             $table->dispatchEvent('Model.beforeFind', [
                 $this,
                 new ArrayObject($this->_options),

src/ORM/Table.php

@@ -1289,6 +1289,7 @@ public function findList(Query $query, array $options)
         );
 
         return $query->formatResults(function ($results) use ($options) {
+            /* @var \Cake\Collection\CollectionInterface $results */
             return $results->combine(
                 $options['keyField'],
                 $options['valueField'],
@@ -1338,6 +1339,7 @@ public function findThreaded(Query $query, array $options)
         $options = $this->_setFieldMatchers($options, ['keyField', 'parentField']);
 
         return $query->formatResults(function ($results) use ($options) {
+            /* @var \Cake\Collection\CollectionInterface $results */
             return $results->nest($options['keyField'], $options['parentField'], $options['nestingKey']);
         });
     }

src/Routing/DispatcherFilter.php

@@ -62,6 +62,8 @@
  *
  * When using the `for` or `when` matchers, conditions will be re-checked on the before and after
  * callback as the conditions could change during the dispatch cycle.
+ *
+ * @mixin \Cake\Core\InstanceConfigTrait
  */
 class DispatcherFilter implements EventListenerInterface
 {