document usage of AbstractQuery#enableResultCache() and #disableResultCache()

someniatko · someniatko · commit 9c88aa8e104f · 2019-07-03T15:49:50.000+03:00
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,10 +1,20 @@
 # Upgrade to 2.7
 
+## Added `Doctrine\ORM\AbstractQuery#enableResultCache()` and `Doctrine\ORM\AbstractQuery#disableResultCache()` methods
+
+Method `Doctrine\ORM\AbstractQuery#useResultCache()` which could be used for both 
+enabling and disabling the cache (depending on passed flag) was split into two.
+
 ## Deprecated: `Doctrine\ORM\EntityManagerInterface#copy()`
 
 Method `Doctrine\ORM\EntityManagerInterface#copy()` never got its implementation and is deprecated.
 It will be removed in 3.0.
 
+## Deprecated: `Doctrine\ORM\AbstractQuery#useResultCache()`
+
+Method `Doctrine\ORM\AbstractQuery#useResultCache()` is deprecated because it is split
+into `enableResultCache()` and `disableResultCache()`. It will be removed in 3.0.
+
 # Upgrade to 2.6
 
 ## Added `Doctrine\ORM\EntityRepository::count()` method
diff --git a/docs/en/reference/caching.rst b/docs/en/reference/caching.rst
@@ -327,7 +327,7 @@ the result cache.
 
     <?php
     $query = $em->createQuery('select u from \Entities\User u');
-    $query->useResultCache(true);
+    $query->enableResultCache();
 
 You can also configure an individual query to use a different
 result cache driver.
@@ -341,12 +341,12 @@ result cache driver.
 
     Setting the result cache driver on the query will
     automatically enable the result cache for the query. If you want to
-    disable it pass false to ``useResultCache()``.
+    disable it, call ``disableResultCache``.
 
     ::
 
         <?php
-        $query->useResultCache(false);
+        $query->disableResultCache();
 
 
 If you want to set the time the cache has to live you can use the
@@ -367,12 +367,12 @@ yourself with the ``setResultCacheId()`` method.
     $query->setResultCacheId('my_custom_id');
 
 You can also set the lifetime and cache ID by passing the values as
-the second and third argument to ``useResultCache()``.
+the first and second argument to ``enableResultCache()``.
 
 .. code-block:: php
 
     <?php
-    $query->useResultCache(true, 3600, 'my_custom_id');
+    $query->enableResultCache(3600, 'my_custom_id');
 
 Metadata Cache
 ~~~~~~~~~~~~~~
diff --git a/docs/en/reference/dql-doctrine-query-language.rst b/docs/en/reference/dql-doctrine-query-language.rst
@@ -1323,7 +1323,7 @@ Result Cache API:
 
     $query->setResultCacheDriver(new ApcCache());
 
-    $query->useResultCache(true)
+    $query->enableResultCache()
           ->setResultCacheLifeTime($seconds = 3600);
 
     $result = $query->getResult(); // cache miss
@@ -1334,8 +1334,8 @@ Result Cache API:
     $query->setResultCacheId('my_query_result');
     $result = $query->getResult(); // saved in given result cache id.
 
-    // or call useResultCache() with all parameters:
-    $query->useResultCache(true, $seconds = 3600, 'my_query_result');
+    // or call enableResultCache() with all parameters:
+    $query->enableResultCache($seconds = 3600, 'my_query_result');
     $result = $query->getResult(); // cache hit!
 
     // Introspection
diff --git a/docs/en/reference/query-builder.rst b/docs/en/reference/query-builder.rst
@@ -330,7 +330,7 @@ a querybuilder instance into a Query object:
 
     // Set additional Query options
     $query->setQueryHint('foo', 'bar');
-    $query->useResultCache('my_cache_id');
+    $query->enableResultCache($seconds = 3600, 'my_cache_id');
 
     // Execute Query
     $result = $query->getResult();
