Merge pull request #7642 from kenjis/docs-caching-cacheQueryString

docs: add missing "Configuring Caching" in Web Page Caching

Author: kenjis

app/Config/Cache.php

@@ -53,12 +53,12 @@ class Cache extends BaseConfig
      * Whether to take the URL query string into consideration when generating
      * output cache files. Valid options are:
      *
-     *    false      = Disabled
-     *    true       = Enabled, take all query parameters into account.
-     *                 Please be aware that this may result in numerous cache
-     *                 files generated for the same page over and over again.
-     *    array('q') = Enabled, but only take into account the specified list
-     *                 of query parameters.
+     *    false = Disabled
+     *    true  = Enabled, take all query parameters into account.
+     *            Please be aware that this may result in numerous cache
+     *            files generated for the same page over and over again.
+     *    ['q'] = Enabled, but only take into account the specified list
+     *            of query parameters.
      *
      * @var bool|string[]
      */

user_guide_src/source/general/caching.rst

@@ -21,15 +21,42 @@ How Does Caching Work?
 
 Caching can be enabled on a per-page basis, and you can set the length
 of time that a page should remain cached before being refreshed. When a
-page is loaded for the first time, the file will be cached using the
-currently configured cache engine. On subsequent page loads, the cache file
+page is loaded for the first time, the page will be cached using the
+currently configured cache engine. On subsequent page loads, the cache
 will be retrieved and sent to the requesting user's browser. If it has
 expired, it will be deleted and refreshed before being sent to the
 browser.
 
 .. note:: The Benchmark tag is not cached so you can still view your page
     load speed when caching is enabled.
 
+Configuring Caching
+===================
+
+Setting Cache Engine
+--------------------
+
+Before using Web Page Caching, you must set the cache engine up by editing
+**app/Config/Cache.php**. See :ref:`libraries-caching-configuring-the-cache`
+for details.
+
+Setting $cacheQueryString
+-------------------------
+
+You can set whether or not to include the query string when generating the cache
+with ``Config\Cache::$cacheQueryString``.
+
+Valid options are:
+
+- ``false``: (default) Disabled. The query string is not taken into account; the
+  same cache is returned for requests with the same URI path but different query
+  strings.
+- ``true``: Enabled, take all query parameters into account. Be aware that this
+  may result in numerous cache generated for the same page over and over
+  again.
+- **array**: Enabled, but only take into account the specified list of query
+  parameters. E.g., ``['q', 'page']``.
+
 Enabling Caching
 ================
 
@@ -46,15 +73,12 @@ the order that it appears, so place it wherever it seems most logical to
 you. Once the tag is in place, your pages will begin being cached.
 
 .. important:: If you change configuration options that might affect
-    your output, you have to manually delete your cache files.
-
-.. note:: Before the cache files can be written you must set the cache
-    engine up by editing **app/Config/Cache.php**.
+    your output, you have to manually delete your cache.
 
 Deleting Caches
 ===============
 
-If you no longer wish to cache a file you can remove the caching tag and
+If you no longer wish to cache a page you can remove the caching tag and
 it will no longer be refreshed when it expires.
 
 .. note:: Removing the tag will not delete the cache immediately. It will

user_guide_src/source/libraries/caching.rst

@@ -23,6 +23,8 @@ You can grab an instance of the cache engine directly through the Services class
 
 .. literalinclude:: caching/002.php
 
+.. _libraries-caching-configuring-the-cache:
+
 *********************
 Configuring the Cache
 *********************