Merge pull request #4640 from greg0ire/make-footgun-more-obvious

Make footgun more obvious

docs/en/reference/caching.rst

@@ -1,10 +1,22 @@
 Caching
 =======
 
-A ``Doctrine\DBAL\Statement`` can automatically cache result sets.
+A ``Doctrine\DBAL\Statement`` can automatically cache result sets. The
+feature is optional though, and by default, no result set is cached.
 
-For this to work an instance of ``Doctrine\Common\Cache\Cache`` must be provided.
-This can be set on the configuration object (optionally it can also be passed at query time):
+To use the result cache, there are three mandatory steps:
+
+1. Configure a global result cache, or provide one at query time.
+2. Provide a cache profile for the result set you want to cache when
+   making a query.
+3. Read the entire result set from the database.
+
+Configuring the result cache
+----------------------------
+
+Any instance of ``Doctrine\Common\Cache\Cache`` can be used as a result
+cache and can be set on the configuration object (optionally it can also
+be passed at query time):
 
 ::
 
@@ -13,29 +25,40 @@ This can be set on the configuration object (optionally it can also be passed at
     $config = $conn->getConfiguration();
     $config->setResultCacheImpl($cache);
 
-To get the result set of a query cached it is necessary to pass a
-``Doctrine\DBAL\Cache\QueryCacheProfile`` instance to the ``executeQuery`` or ``executeCacheQuery``
-instance. The difference between these two methods is that the former does not
-require this instance, while the later has this instance as a required parameter:
+Providing a cache profile
+-------------------------
+
+To get the result set of a query cached, it is necessary to pass a
+``Doctrine\DBAL\Cache\QueryCacheProfile`` instance to the
+``executeQuery()`` or ``executeCacheQuery()`` methods. The difference
+between these two methods is that the former has the cache profile as an
+optional argument, whereas it is required when calling the latter:
 
 ::
 
     <?php
     $stmt = $conn->executeQuery($query, $params, $types, new QueryCacheProfile(0, "some key"));
     $stmt = $conn->executeCacheQuery($query, $params, $types, new QueryCacheProfile(0, "some key"));
 
-It is also possible to pass in a ``Doctrine\Common\Cache\Cache`` instance into the
-constructor of ``Doctrine\DBAL\Cache\QueryCacheProfile`` in which case it overrides
-the default cache instance:
+As stated before, it is also possible to pass in a
+``Doctrine\Common\Cache\Cache`` instance into the constructor of
+``Doctrine\DBAL\Cache\QueryCacheProfile`` in which case it overrides the
+default cache instance:
 
 ::
 
     <?php
     $cache = new \Doctrine\Common\Cache\FilesystemCache(__DIR__);
     new QueryCacheProfile(0, "some key", $cache);
 
-In order for the data to actually be cached its necessary to ensure that the entire
-result set is read (the easiest way to ensure this is to use one of the ``fetchAll*()`` methods):
+Reading the entire result set
+-----------------------------
+
+Caching half a result set would cause bugs if a subsequent caller needed
+more rows from that same result sets. To be able to cache the entire
+result set, it must be fetched entirely from the database, and not all
+APIs do that. The easiest way to ensure that is to use one of the
+``fetchAll*()`` methods:
 
 ::
 
@@ -45,4 +68,6 @@ result set is read (the easiest way to ensure this is to use one of the ``fetchA
 
 .. warning::
 
-    When using the cache layer not all fetch modes are supported. See the code of the ``Doctrine\DBAL\Cache\ResultCacheStatement`` for details.
+    When using the cache layer not all fetch modes are supported. See
+    the code of the ``Doctrine\DBAL\Cache\ResultCacheStatement`` for
+    details.

lib/Doctrine/DBAL/Cache/ResultCacheStatement.php

@@ -117,6 +117,9 @@ public function getIterator()
     }
 
     /**
+     * Be warned that you will need to call this method until no rows are
+     * available for caching to happen.
+     *
      * {@inheritdoc}
      *
      * @deprecated Use fetchNumeric(), fetchAssociative() or fetchOne() instead.
@@ -189,6 +192,9 @@ public function fetchAll($fetchMode = null, $fetchArgument = null, $ctorArgs = n
     }
 
     /**
+     * Be warned that you will need to call this method until no rows are
+     * available for caching to happen.
+     *
      * {@inheritdoc}
      *
      * @deprecated Use fetchOne() instead.
@@ -202,6 +208,9 @@ public function fetchColumn($columnIndex = 0)
     }
 
     /**
+     * Be warned that you will need to call this method until no rows are
+     * available for caching to happen.
+     *
      * {@inheritdoc}
      */
     public function fetchNumeric()
@@ -216,6 +225,9 @@ public function fetchNumeric()
     }
 
     /**
+     * Be warned that you will need to call this method until no rows are
+     * available for caching to happen.
+     *
      * {@inheritdoc}
      */
     public function fetchAssociative()
@@ -224,6 +236,9 @@ public function fetchAssociative()
     }
 
     /**
+     * Be warned that you will need to call this method until no rows are
+     * available for caching to happen.
+     *
      * {@inheritdoc}
      */
     public function fetchOne()