From 7c2ab7fff87aaadcf6f267ae053f7daf9270ef5d Mon Sep 17 00:00:00 2001 From: Simon Harris Date: Thu, 31 Jul 2014 16:45:33 +0100 Subject: [PATCH] Changes for grammar and clarity --- docs/en/reference/caching.rst | 73 +++++++++++++++++------------------ 1 file changed, 36 insertions(+), 37 deletions(-) diff --git a/docs/en/reference/caching.rst b/docs/en/reference/caching.rst index ff5cadd7b..0f18e8a20 100644 --- a/docs/en/reference/caching.rst +++ b/docs/en/reference/caching.rst @@ -4,9 +4,9 @@ Caching Doctrine provides cache drivers in the ``Common`` package for some of the most popular caching implementations such as APC, Memcache and Xcache. We also provide an ``ArrayCache`` driver which stores -the data in a PHP array. Obviously, the cache does not live between -requests but this is useful for testing in a development -environment. +the data in a PHP array. Obviously, when using ``ArrayCache``, the +cache does not persist between requests, but this is useful for +testing in a development environment. Cache Drivers ------------- @@ -14,20 +14,19 @@ Cache Drivers The cache drivers follow a simple interface that is defined in ``Doctrine\Common\Cache\Cache``. All the cache drivers extend a base class ``Doctrine\Common\Cache\AbstractCache`` which implements -the before mentioned interface. +this interface. -The interface defines the following methods for you to publicly -use. +The interface defines the following public methods for you to implement: -- fetch($id) - Fetches an entry from the cache. -- contains($id) - Test if an entry exists in the cache. -- save($id, $data, $lifeTime = false) - Puts data into the cache. -- delete($id) - Deletes a cache entry. +- fetch($id) - Fetches an entry from the cache +- contains($id) - Test if an entry exists in the cache +- save($id, $data, $lifeTime = false) - Puts data into the cache +- delete($id) - Deletes a cache entry Each driver extends the ``AbstractCache`` class which defines a few abstract protected methods that each of the drivers must -implement. +implement: - \_doFetch($id) @@ -35,8 +34,8 @@ implement. - \_doSave($id, $data, $lifeTime = false) - \_doDelete($id) -The public methods ``fetch()``, ``contains()``, etc. utilize the -above protected methods that are implemented by the drivers. The +The public methods ``fetch()``, ``contains()`` etc. use the +above protected methods which are implemented by the drivers. The code is organized this way so that the protected methods in the drivers do the raw interaction with the cache implementation and the ``AbstractCache`` can build custom functionality on top of @@ -65,7 +64,7 @@ Memcache In order to use the Memcache cache driver you must have it compiled and enabled in your php.ini. You can read about Memcache -` on the PHP website `_. It will +`on the PHP website `_. 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. @@ -90,7 +89,7 @@ Memcache. In order to use the Memcached cache driver you must have it compiled and enabled in your php.ini. You can read about Memcached -` on the PHP website `_. It will +`on the PHP website `_. 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. @@ -129,10 +128,10 @@ Redis ~~~~~ In order to use the Redis cache driver you must have it compiled -and enabled in your php.ini. You can read about what is Redis +and enabled in your php.ini. You can read about what Redis is `from here `_. Also check `A PHP extension for Redis `_ for how you can use -and install Redis PHP extension. +and install the Redis PHP extension. Below is a simple example of how you could use the Redis cache driver by itself. @@ -151,8 +150,8 @@ Using Cache Drivers ------------------- In this section we'll describe how you can fully utilize the API of -the cache drivers to save cache, check if some cache exists, fetch -the cached data and delete the cached data. We'll use the +the cache drivers to save data to a cache, check if some cached data +exists, fetch the cached data and delete the cached data. We'll use the ``ArrayCache`` implementation as our example here. .. code-block:: php @@ -163,7 +162,7 @@ the cached data and delete the cached data. We'll use the Saving ~~~~~~ -To save some data to the cache driver it is as simple as using the +Saving some data to the cache driver is as simple as using the ``save()`` method. .. code-block:: php @@ -172,7 +171,7 @@ To save some data to the cache driver it is as simple as using the $cacheDriver->save('cache_id', 'my_data'); The ``save()`` method accepts three arguments which are described -below. +below: - ``$id`` - The cache id @@ -195,7 +194,7 @@ object, etc. Checking ~~~~~~~~ -Checking whether some cache exists is very simple, just use the +Checking whether cached data exists is very simple: just use the ``contains()`` method. It accepts a single argument which is the ID of the cache entry. @@ -213,7 +212,7 @@ Fetching Now if you want to retrieve some cache entry you can use the ``fetch()`` method. It also accepts a single argument just like -``contains()`` which is the ID of the cache entry. +``contains()`` which is again the ID of the cache entry. .. code-block:: php @@ -249,7 +248,7 @@ the ``deleteAll()`` method. Namespaces ~~~~~~~~~~ -If you heavily use caching in your application and utilize it in +If you heavily use caching in your application and use it in multiple parts of your application, or use it in different applications on the same server you may have issues with cache naming collisions. This can be worked around by using namespaces. @@ -265,8 +264,8 @@ Integrating with the ORM ------------------------ The Doctrine ORM package is tightly integrated with the cache -drivers to allow you to improve performance of various aspects of -Doctrine by just simply making some additional configurations and +drivers to allow you to improve the performance of various aspects of +Doctrine by simply making some additional configurations and method calls. Query Cache @@ -374,9 +373,9 @@ the cache driver. Clearing the Cache ------------------ -We've already shown you previously how you can use the API of the +We've already shown you how you can use the API of the cache drivers to manually delete cache entries. For your -convenience we offer a command line task for you to help you with +convenience we offer a command line task to help you with clearing the query, result and metadata cache. From the Doctrine command line you can run the following command. @@ -408,7 +407,7 @@ To clear the result cache use the ``--result`` option. $ ./doctrine clear-cache --result When you use the ``--result`` option you can use some other options -to be more specific about what queries result sets you want to +to be more specific about which queries' result sets you want to clear. Just like the API of the cache drivers you can clear based on an @@ -418,19 +417,19 @@ ID, regular expression, prefix or suffix. $ ./doctrine clear-cache --result --id=cache_id -Or if you want to clear based on a regular expressions. +Or if you want to clear based on a regular expressions: .. code-block:: php $ ./doctrine clear-cache --result --regex=users_.* -Or with a prefix. +Or with a prefix: .. code-block:: php $ ./doctrine clear-cache --result --prefix=users_ -And finally with a suffix. +And finally with a suffix: .. code-block:: php @@ -447,15 +446,15 @@ And finally with a suffix. Cache Slams ----------- -Something to be careful of when utilizing the cache drivers is -cache slams. If you have a heavily trafficked website with some +Something to be careful of when using the cache drivers is +"cache slams". Imagine you have a heavily trafficked website with some code that checks for the existence of a cache record and if it does not exist it generates the information and saves it to the cache. -Now if 100 requests were issued all at the same time and each one -sees the cache does not exist and they all try and insert the same +Now, if 100 requests were issued all at the same time and each one +sees the cache does not exist and they all try to insert the same cache entry it could lock up APC, Xcache, etc. and cause problems. Ways exist to work around this, like pre-populating your cache and -not letting your users requests populate the cache. +not letting your users' requests populate the cache. You can read more about cache slams `in this blog post `_.