From 162c62f38fdfd395358017b203807d6f508adeea Mon Sep 17 00:00:00 2001
From: Woody Gilk <woody.gilk@gmail.com>
Date: Sat, 1 Dec 2018 23:06:38 -0600
Subject: [PATCH] Prefer PhpFileCache for caching docs

Removes APC and XCache because they are deprecated.

Removes APCu because it is not as performant as PhpFileCache and cannot
be cleared using console tools.
---
 docs/en/reference/caching.rst | 85 +++++++++++++++--------------------
 1 file changed, 36 insertions(+), 49 deletions(-)

diff --git a/docs/en/reference/caching.rst b/docs/en/reference/caching.rst
index 4423fb130f7..c0ba94912b7 100644
--- a/docs/en/reference/caching.rst
+++ b/docs/en/reference/caching.rst
@@ -45,40 +45,24 @@ This documentation does not cover every single cache driver included
 with Doctrine. For an up-to-date-list, see the
 `cache directory on GitHub <https://github.com/doctrine/cache/tree/master/lib/Doctrine/Common/Cache>`.
 
-APC
-~~~
-
-In order to use the APC cache driver you must have it compiled and
-enabled in your php.ini. You can read about APC
-`in the PHP Documentation <http://us2.php.net/apc>`_. It will give
-you a little background information about what it is and how you
-can use it as well as how to install it.
-
-Below is a simple example of how you could use the APC cache driver
-by itself.
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver = new \Doctrine\Common\Cache\ApcCache();
-    $cacheDriver->save('cache_id', 'my_data');
+PhpFileCache
+~~~~~~~~~~~~
 
-APCu
-~~~~
+The preferred cache driver is ``PhpFileCache``. This driver serializes
+cache items and writes them to a file. This allows for opcode caching
+to be used and provides high performance in most scenarios.
 
-In order to use the APCu cache driver you must have it compiled and
-enabled in your php.ini. You can read about APCu
-`in the PHP Documentation <http://us2.php.net/apcu>`_. It will give
-you a little background information about what it is and how you
-can use it as well as how to install it.
+In order to use the ``PhpFileCache`` driver it must be able to write to
+a directory.
 
-Below is a simple example of how you could use the APCu cache driver
-by itself.
+Below is an example of how to use the ``PhpFileCache`` driver by itself.
 
 .. code-block:: php
 
     <?php
-    $cacheDriver = new \Doctrine\Common\Cache\ApcuCache();
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+        '/path/to/writable/directory'
+    );
     $cacheDriver->save('cache_id', 'my_data');
 
 Memcache
@@ -128,24 +112,6 @@ driver by itself.
     $cacheDriver->setMemcached($memcached);
     $cacheDriver->save('cache_id', 'my_data');
 
-Xcache
-~~~~~~
-
-In order to use the Xcache cache driver you must have it compiled
-and enabled in your php.ini. You can read about Xcache
-`here <http://xcache.lighttpd.net/>`_. It will give you a little
-background information about what it is and how you can use it as
-well as how to install it.
-
-Below is a simple example of how you could use the Xcache cache
-driver by itself.
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver = new \Doctrine\Common\Cache\XcacheCache();
-    $cacheDriver->save('cache_id', 'my_data');
-
 Redis
 ~~~~~
 
@@ -304,8 +270,11 @@ use on your ORM configuration.
 .. code-block:: php
 
     <?php
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCacheCache(
+        '/path/to/writable/directory'
+    );
     $config = new \Doctrine\ORM\Configuration();
-    $config->setQueryCacheImpl(new \Doctrine\Common\Cache\ApcuCache());
+    $config->setQueryCacheImpl($cacheDriver);
 
 Result Cache
 ~~~~~~~~~~~~
@@ -318,7 +287,11 @@ cache implementation.
 .. code-block:: php
 
     <?php
-    $config->setResultCacheImpl(new \Doctrine\Common\Cache\ApcuCache());
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCacheCache(
+        '/path/to/writable/directory'
+    );
+    $config = new \Doctrine\ORM\Configuration();
+    $config->setResultCacheImpl($cacheDriver);
 
 Now when you're executing DQL queries you can configure them to use
 the result cache.
@@ -335,7 +308,11 @@ result cache driver.
 .. code-block:: php
 
     <?php
-    $query->setResultCacheDriver(new \Doctrine\Common\Cache\ApcuCache());
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCacheCache(
+        '/path/to/writable/directory'
+    );
+    $config = new \Doctrine\ORM\Configuration();
+    $query->setResultCacheDriver($cacheDriver);
 
 .. note::
 
@@ -387,7 +364,11 @@ first.
 .. code-block:: php
 
     <?php
-    $config->setMetadataCacheImpl(new \Doctrine\Common\Cache\ApcuCache());
+    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCacheCache(
+        '/path/to/writable/directory'
+    );
+    $config = new \Doctrine\ORM\Configuration();
+    $config->setMetadataCacheImpl($cacheDriver);
 
 Now the metadata information will only be parsed once and stored in
 the cache driver.
@@ -423,6 +404,12 @@ To clear the result cache use the ``orm:clear-cache:result`` task.
 All these tasks accept a ``--flush`` option to flush the entire
 contents of the cache instead of invalidating the entries.
 
+.. note::
+
+    None of these tasks will work with APC, APCu, or XCache drivers
+    because the memory that the cache is stored in is only accessible
+    to the webserver.
+
 Cache Chaining
 --------------