DDC-126 - Make Query, NativeQuery Fluent-Interfaces for all their set Methods,...

DDC-126 - Make Query, NativeQuery Fluent-Interfaces for all their set Methods, renamed setExpireQueryCache() and setExpireResultCache() to expireQueryCache() and expireResultCache(). Updated UPGRADE_TO_2_0 document accordingly.

UPGRADE_TO_2_0

@@ -2,6 +2,13 @@
 > This document does not describe how to upgrade from Doctrine 1.x to Doctrine 2 as this is a more
 > complicated process.
 
+# Upgrade from 2.0-ALPHA3 to 2.0-ALPHA4
+
+## Renamed Methods
+
+    * Doctrine\ORM\AbstractQuery::setExpireResultCache() -> expireResultCache()
+    * Doctrine\ORM\Query::setExpireQueryCache() -> expireQueryCache()
+
 # Upgrade from 2.0-ALPHA2 to 2.0-ALPHA3
 
 This section details the changes made to Doctrine 2.0-ALPHA3 to make it easier for you

lib/Doctrine/ORM/AbstractQuery.php

@@ -184,39 +184,45 @@ abstract class AbstractQuery
      *
      * @param string|integer $key The parameter position or name.
      * @param mixed $value The parameter value.
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setParameter($key, $value)
     {
         $this->_params[$key] = $value;
+        return $this;
     }
     
     /**
      * Sets a collection of query parameters.
      *
      * @param array $params
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setParameters(array $params)
     {
         foreach ($params as $key => $value) {
             $this->setParameter($key, $value);
         }
+        return $this;
     }
 
     /**
      * Sets the ResultSetMapping that should be used for hydration.
      *
      * @param ResultSetMapping $rsm
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setResultSetMapping($rsm)
     {
         $this->_resultSetMapping = $rsm;
+        return $this;
     }
 
     /**
      * Defines a cache driver to be used for caching result sets.
      *
      * @param Doctrine\Common\Cache\Cache $driver Cache driver
-     * @return Doctrine\ORM\Query
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setResultCacheDriver($resultCacheDriver = null)
     {
@@ -227,6 +233,7 @@ abstract class AbstractQuery
         if ($resultCacheDriver) {
             $this->_useResultCache = true;
         }
+        return $this;
     }
 
     /**
@@ -263,6 +270,7 @@ abstract class AbstractQuery
      * Defines how long the result cache will be active before expire.
      *
      * @param integer $timeToLive How long the cache entry is valid
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setResultCacheLifetime($timeToLive)
     {
@@ -271,6 +279,7 @@ abstract class AbstractQuery
         }
 
         $this->_resultCacheTTL = $timeToLive;
+        return $this;
     }
 
     /**
@@ -287,11 +296,12 @@ abstract class AbstractQuery
      * Defines if the result cache is active or not.
      *
      * @param boolean $expire Whether or not to force resultset cache expiration.
-     * @return Doctrine_ORM_Query
+     * @return Doctrine\ORM\AbstractQuery
      */
-    public function setExpireResultCache($expire = true)
+    public function expireResultCache($expire = true)
     {
         $this->_expireResultCache = $expire;
+        return $this;
     }
 
     /**
@@ -309,10 +319,12 @@ abstract class AbstractQuery
      *
      * @param integer $hydrationMode Doctrine processing mode to be used during hydration process.
      *                               One of the Query::HYDRATE_* constants.
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setHydrationMode($hydrationMode)
     {
         $this->_hydrationMode = $hydrationMode;
+        return $this;
     }
 
     /**
@@ -406,10 +418,12 @@ abstract class AbstractQuery
      *
      * @param string $name The name of the hint.
      * @param mixed $value The value of the hint.
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setHint($name, $value)
     {
         $this->_hints[$name] = $value;
+        return $this;
     }
 
     /**
@@ -502,11 +516,13 @@ abstract class AbstractQuery
      * If this is not explicitely set by the developer then a hash is automatically
      * generated for you.
      *
-     * @param string $id 
+     * @param string $id
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setResultCacheId($id)
     {
         $this->_resultCacheId = $id;
+        return $this;
     }
 
     /**

lib/Doctrine/ORM/EntityManager.php

@@ -245,7 +245,7 @@ class EntityManager
      *
      * @param string $sql
      * @param ResultSetMapping $rsm The ResultSetMapping to use.
-     * @return Query
+     * @return NativeQuery
      */
     public function createNativeQuery($sql, \Doctrine\ORM\Query\ResultSetMapping $rsm)
     {

lib/Doctrine/ORM/NativeQuery.php

@@ -46,10 +46,12 @@ final class NativeQuery extends AbstractQuery
      * Sets the SQL of the query.
      *
      * @param string $sql
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setSql($sql)
     {
         $this->_sql = $sql;
+        return $this;
     }
 
     /**

lib/Doctrine/ORM/Query.php

@@ -296,7 +296,7 @@ final class Query extends AbstractQuery
      * @param boolean $expire Whether or not to force query cache expiration.
      * @return Query This query instance.
      */
-    public function setExpireQueryCache($expire = true)
+    public function expireQueryCache($expire = true)
     {
         $this->_expireQueryCache = $expire;
 
@@ -327,6 +327,7 @@ final class Query extends AbstractQuery
      * Sets a DQL query string.
      *
      * @param string $dqlQuery DQL Query
+     * @return Doctrine\ORM\AbstractQuery
      */
     public function setDql($dqlQuery)
     {
@@ -334,6 +335,7 @@ final class Query extends AbstractQuery
             $this->_dql = $dqlQuery;
             $this->_state = self::STATE_DIRTY;
         }
+        return $this;
     }
 
     /**

tests/Doctrine/Tests/ORM/Functional/NativeQueryTest.php

@@ -140,5 +140,22 @@ class NativeQueryTest extends \Doctrine\Tests\OrmFunctionalTestCase
         $this->assertEquals(10827, $users[0]->getAddress()->getZipCode());
         $this->assertEquals('Berlin', $users[0]->getAddress()->getCity());
     }
+
+    public function testFluentInterface()
+    {
+        $rsm = new ResultSetMapping;
+
+        $q = $this->_em->createNativeQuery('SELECT id, name, status, phonenumber FROM cms_users INNER JOIN cms_phonenumbers ON id = user_id WHERE username = ?', $rsm);
+        $q2 = $q->setSql('foo', $rsm)
+          ->setResultSetMapping($rsm)
+          ->expireResultCache(true)
+          ->setHint('foo', 'bar')
+          ->setParameter(1, 'foo')
+          ->setParameters(array(2 => 'bar'))
+          ->setResultCacheDriver(null)
+          ->setResultCacheLifetime(3500);
+
+        $this->assertSame($q, $q2);
+    }
 }
 

tests/Doctrine/Tests/ORM/Functional/QueryTest.php

@@ -175,5 +175,25 @@ class QueryTest extends \Doctrine\Tests\OrmFunctionalTestCase
         $this->_em->flush();
         $this->_em->clear();
     }
+
+    public function testFluentQueryInterface()
+    {
+        $q = $this->_em->createQuery("select a from Doctrine\Tests\Models\CMS\CmsArticle a");
+        $q2 = $q->expireQueryCache(true)
+          ->setQueryCacheLifetime(3600)
+          ->setQueryCacheDriver(null)
+          ->expireResultCache(true)
+          ->setHint('foo', 'bar')
+          ->setHint('bar', 'baz')
+          ->setParameter(1, 'bar')
+          ->setParameters(array(2 => 'baz'))
+          ->setResultCacheDriver(null)
+          ->setResultCacheId('foo')
+          ->setDql('foo')
+          ->setFirstResult(10)
+          ->setMaxResults(10);
+
+        $this->assertSame($q2, $q);
+    }
 }