Merge pull request #11822 from cakephp/3.next-depr-contain

Deprecate getter code smell in contain() in favor of getContain().

src/ORM/Association.php

@@ -1262,7 +1262,7 @@ abstract class Association
     protected function _bindNewAssociations($query, $surrogate, $options)
     {
         $loader = $surrogate->getEagerLoader();
-        $contain = $loader->contain();
+        $contain = $loader->getContain();
         $matching = $loader->getMatching();
 
         if (!$contain && !$matching) {
@@ -1275,7 +1275,9 @@ abstract class Association
         }
 
         $eagerLoader = $query->getEagerLoader();
-        $eagerLoader->contain($newContain);
+        if ($newContain) {
+            $eagerLoader->contain($newContain);
+        }
 
         foreach ($matching as $alias => $value) {
             $eagerLoader->setMatching(

src/ORM/EagerLoader.php

@@ -113,6 +113,8 @@ class EagerLoader
      * this allows this object to calculate joins or any additional queries that
      * must be executed to bring the required associated data.
      *
+     * The getter part is deprecated as of 3.6.0. Use getContain() instead.
+     *
      * Accepted options per passed association:
      *
      * - foreignKey: Used to set a different field to match both tables, if set to false
@@ -134,7 +136,12 @@ class EagerLoader
     public function contain($associations = [], callable $queryBuilder = null)
     {
         if (empty($associations)) {
-            return $this->_containments;
+            deprecationWarning(
+                'Using EagerLoader::contain() as getter is deprecated. ' .
+                'Use getContain() instead.'
+            );
+
+            return $this->getContain();
         }
 
         if ($queryBuilder) {
@@ -161,6 +168,19 @@ class EagerLoader
     }
 
     /**
+     * Gets the list of associations that should be eagerly loaded along for a
+     * specific table using when a query is provided. The list of associated tables
+     * passed to this method must have been previously set as associations using the
+     * Table API.
+     *
+     * @return array Containments.
+     */
+    public function getContain()
+    {
+        return $this->_containments;
+    }
+
+    /**
      * Remove any existing non-matching based containments.
      *
      * This will reset/clear out any contained associations that were not
@@ -276,7 +296,7 @@ class EagerLoader
             $this->_matching = new static();
         }
 
-        return $this->_matching->contain();
+        return $this->_matching->getContain();
     }
 
     /**
@@ -705,7 +725,7 @@ class EagerLoader
     {
         $map = [];
 
-        if (!$this->getMatching() && !$this->contain() && empty($this->_joinsMap)) {
+        if (!$this->getMatching() && !$this->getContain() && empty($this->_joinsMap)) {
             return $map;
         }
 

src/ORM/LazyEagerLoader.php

@@ -51,7 +51,7 @@ class LazyEagerLoader
 
         $entities = new Collection($entities);
         $query = $this->_getQuery($entities, $contain, $source);
-        $associations = array_keys($query->contain());
+        $associations = array_keys($query->getContain());
 
         $entities = $this->_injectResults($entities, $query, $associations, $source);
 

src/ORM/Query.php

@@ -408,7 +408,7 @@ class Query extends DatabaseQuery implements JsonSerializable, QueryInterface
      *
      * If called with no arguments, this function will return an array with
      * with the list of previously configured associations to be contained in the
-     * result.
+     * result. This getter part is deprecated as of 3.6.0. Use getContain() instead.
      *
      * If called with an empty first argument and `$override` is set to true, the
      * previous list will be emptied.
@@ -428,7 +428,12 @@ class Query extends DatabaseQuery implements JsonSerializable, QueryInterface
         }
 
         if ($associations === null) {
-            return $loader->contain();
+            deprecationWarning(
+                'Using Query::contain() as getter is deprecated. ' .
+                'Use getContain() instead.'
+            );
+
+            return $loader->getContain();
         }
 
         $queryBuilder = null;
@@ -436,13 +441,23 @@ class Query extends DatabaseQuery implements JsonSerializable, QueryInterface
             $queryBuilder = $override;
         }
 
-        $result = $loader->contain($associations, $queryBuilder);
-        $this->_addAssociationsToTypeMap($this->repository(), $this->getTypeMap(), $result);
+        if ($associations) {
+            $loader->contain($associations, $queryBuilder);
+        }
+        $this->_addAssociationsToTypeMap($this->repository(), $this->getTypeMap(), $loader->getContain());
 
         return $this;
     }
 
     /**
+     * @return array
+     */
+    public function getContain()
+    {
+        return $this->getEagerLoader()->getContain();
+    }
+
+    /**
      * Clears the contained associations from the current query.
      *
      * @return $this
@@ -1258,7 +1273,7 @@ class Query extends DatabaseQuery implements JsonSerializable, QueryInterface
             'buffered' => $this->_useBufferedResults,
             'formatters' => count($this->_formatters),
             'mapReducers' => count($this->_mapReduce),
-            'contain' => $eagerLoader ? $eagerLoader->contain() : [],
+            'contain' => $eagerLoader ? $eagerLoader->getContain() : [],
             'matching' => $eagerLoader ? $eagerLoader->getMatching() : [],
             'extraOptions' => $this->_options,
             'repository' => $this->_repository

tests/TestCase/ORM/Association/HasManyTest.php

@@ -303,6 +303,8 @@ class HasManyTest extends TestCase
 
         $association = new HasMany('Articles', $config);
         $keys = [1, 2, 3, 4];
+
+        /** @var \Cake\ORM\Query $query */
         $query = $this->article->query();
         $query->addDefaultTypes($this->article->Comments->getSource());
 
@@ -336,7 +338,7 @@ class HasManyTest extends TestCase
 
         $expected = new OrderByExpression(['title' => 'DESC']);
         $this->assertOrderClause($expected, $query);
-        $this->assertArrayHasKey('Comments', $query->contain());
+        $this->assertArrayHasKey('Comments', $query->getContain());
     }
 
     /**
@@ -382,6 +384,8 @@ class HasManyTest extends TestCase
         ];
         $association = new HasMany('Articles', $config);
         $keys = [1, 2, 3, 4];
+
+        /** @var \Cake\ORM\Query $query */
         $query = $this->article->query();
         $this->article->method('find')
             ->with('all')

tests/TestCase/ORM/EagerLoaderTest.php

@@ -235,7 +235,7 @@ class EagerLoaderTest extends TestCase
             ]])
             ->will($this->returnValue($query));
 
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain($contains);
         $query->select('foo.id')->setEagerLoader($loader)->sql();
     }
@@ -248,7 +248,7 @@ class EagerLoaderTest extends TestCase
      */
     public function testContainDotNotation()
     {
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain([
             'clients.orders.stuff',
             'clients.companies.categories' => ['conditions' => ['a >' => 1]]
@@ -265,7 +265,7 @@ class EagerLoaderTest extends TestCase
                 ]
             ]
         ];
-        $this->assertEquals($expected, $loader->contain());
+        $this->assertEquals($expected, $loader->getContain());
         $loader->contain([
             'clients.orders' => ['fields' => ['a', 'b']],
             'clients' => ['sort' => ['a' => 'desc']],
@@ -273,7 +273,7 @@ class EagerLoaderTest extends TestCase
 
         $expected['clients']['orders'] += ['fields' => ['a', 'b']];
         $expected['clients'] += ['sort' => ['a' => 'desc']];
-        $this->assertEquals($expected, $loader->contain());
+        $this->assertEquals($expected, $loader->getContain());
     }
 
     /**
@@ -283,7 +283,7 @@ class EagerLoaderTest extends TestCase
      */
     public function testContainKeyValueNotation()
     {
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain([
             'clients',
             'companies' => 'categories',
@@ -296,7 +296,7 @@ class EagerLoaderTest extends TestCase
                 ],
             ],
         ];
-        $this->assertEquals($expected, $loader->contain());
+        $this->assertEquals($expected, $loader->getContain());
     }
 
     /**
@@ -308,7 +308,7 @@ class EagerLoaderTest extends TestCase
     {
         $builder = function ($query) {
         };
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain([
             'clients.orders.stuff' => ['fields' => ['a']],
             'clients' => $builder
@@ -322,14 +322,14 @@ class EagerLoaderTest extends TestCase
                 'queryBuilder' => $builder
             ]
         ];
-        $this->assertEquals($expected, $loader->contain());
+        $this->assertEquals($expected, $loader->getContain());
 
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain([
             'clients.orders.stuff' => ['fields' => ['a']],
             'clients' => ['queryBuilder' => $builder]
         ]);
-        $this->assertEquals($expected, $loader->contain());
+        $this->assertEquals($expected, $loader->getContain());
     }
 
     /**
@@ -341,7 +341,7 @@ class EagerLoaderTest extends TestCase
     {
         $builder = function ($query) {
         };
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain('clients', $builder);
 
         $expected = [
@@ -349,7 +349,7 @@ class EagerLoaderTest extends TestCase
                 'queryBuilder' => $builder
             ]
         ];
-        $this->assertEquals($expected, $loader->contain());
+        $this->assertEquals($expected, $loader->getContain());
     }
 
     /**
@@ -363,7 +363,7 @@ class EagerLoaderTest extends TestCase
 
         $builder = function ($query) {
         };
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain(['clients'], $builder);
 
         $expected = [
@@ -371,7 +371,7 @@ class EagerLoaderTest extends TestCase
                 'queryBuilder' => $builder
             ]
         ];
-        $this->assertEquals($expected, $loader->contain());
+        $this->assertEquals($expected, $loader->getContain());
     }
 
     /**
@@ -381,7 +381,7 @@ class EagerLoaderTest extends TestCase
      */
     public function testContainMergeBuilders()
     {
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain([
             'clients' => function ($query) {
                 return $query->select(['a']);
@@ -392,7 +392,7 @@ class EagerLoaderTest extends TestCase
                 return $query->select(['b']);
             }
         ]);
-        $builder = $loader->contain()['clients']['queryBuilder'];
+        $builder = $loader->getContain()['clients']['queryBuilder'];
         $table = $this->getTableLocator()->get('foo');
         $query = new Query($this->connection, $table);
         $query = $builder($query);
@@ -417,7 +417,7 @@ class EagerLoaderTest extends TestCase
 
         $table = $this->getTableLocator()->get('foo');
         $query = new Query($this->connection, $table);
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain($contains);
         $query->select('foo.id');
         $loader->attachAssociations($query, $table, true);
@@ -502,7 +502,7 @@ class EagerLoaderTest extends TestCase
             ->setConstructorArgs([$this->connection, $this->table])
             ->getMock();
 
-        $loader = new EagerLoader;
+        $loader = new EagerLoader();
         $loader->contain($contains);
         $normalized = $loader->normalized($this->table);
         $this->assertEquals('clients', $normalized['clients']->aliasPath());

tests/TestCase/ORM/QueryTest.php

@@ -923,7 +923,7 @@ class QueryTest extends TestCase
         $this->assertEquals($expected, $query->clause('having'));
 
         $expected = ['articles' => []];
-        $this->assertEquals($expected, $query->contain());
+        $this->assertEquals($expected, $query->getContain());
     }
 
     /**
@@ -1815,18 +1815,19 @@ class QueryTest extends TestCase
             ->setConstructorArgs([$this->connection, $this->table])
             ->getMock();
 
+        /** @var \Cake\ORM\Query $query */
         $query->contain([
             'Articles'
         ]);
 
-        $result = $query->contain();
+        $result = $query->getContain();
         $this->assertInternalType('array', $result);
         $this->assertNotEmpty($result);
 
         $result = $query->clearContain();
         $this->assertInstanceOf(Query::class, $result);
 
-        $result = $query->contain();
+        $result = $query->getContain();
         $this->assertInternalType('array', $result);
         $this->assertEmpty($result);
     }
@@ -1983,13 +1984,13 @@ class QueryTest extends TestCase
 
         $query = $table->find();
         $query->contain(['Comments']);
-        $this->assertEquals(['Comments'], array_keys($query->contain()));
+        $this->assertEquals(['Comments'], array_keys($query->getContain()));
 
         $query->contain(['Authors'], true);
-        $this->assertEquals(['Authors'], array_keys($query->contain()));
+        $this->assertEquals(['Authors'], array_keys($query->getContain()));
 
         $query->contain(['Comments', 'Authors'], true);
-        $this->assertEquals(['Comments', 'Authors'], array_keys($query->contain()));
+        $this->assertEquals(['Comments', 'Authors'], array_keys($query->getContain()));
     }
 
     /**
@@ -3540,8 +3541,8 @@ class QueryTest extends TestCase
 
         $results = $table->find()
             ->enableHydration(false)
-            ->matching('articles', function ($q) {
-                return $q->notMatching('tags', function ($q) {
+            ->matching('articles', function (Query $q) {
+                return $q->notMatching('tags', function (Query $q) {
                     return $q->where(['tags.name' => 'tag3']);
                 });
             })
@@ -3599,7 +3600,7 @@ class QueryTest extends TestCase
         $result = $table
             ->find()
             ->contain([
-                'Comments' => function ($query) use ($table) {
+                'Comments' => function (Query $query) use ($table) {
                     return $query->selectAllExcept($table->Comments, ['published']);
                 }
             ])