Split CacheMiddleware up into two parts -- an update-cache and a fetch-from-cache middleware. This lets you run each half of the cache middleware at the correct time to avoid bad interactions between the cache middleware and other middleware that must modify the cache key (like the locale middleware).

CacheMiddleware itself is still around for backwards-compatibility and as a hook point for the cache decorator, but the documentation has been updated to point people towards the two-part caching middleware.

Refs #730.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@8260 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 29 insertions, 14 deletions

diff --git a/docs/cache.txt b/docs/cache.txt
index d22dd91994..4ca9cbef72 100644
--- a/docs/cache.txt
+++ b/docs/cache.txt
@@ -231,17 +231,25 @@ arguments.
 The per-site cache
 ==================
 
+**New in Django development version** (previous versions of Django only provided a single ``CacheMiddleware`` instead of the two pieces described below).
+
 Once the cache is set up, the simplest way to use caching is to cache your
-entire site. Just add ``'django.middleware.cache.CacheMiddleware'`` to your
+entire site. You'll need to add
+``'django.middleware.cache.UpdateCacheMiddleware'`` and
+``'django.middleware.cache.FetchFromCacheMiddleware' to your
 ``MIDDLEWARE_CLASSES`` setting, as in this example::
 
     MIDDLEWARE_CLASSES = (
-        'django.middleware.cache.CacheMiddleware',
+        'django.middleware.cache.UpdateCacheMiddleware',
         'django.middleware.common.CommonMiddleware',
+        'django.middleware.cache.FetchFromCacheMiddleware',
     )
 
-(The order of ``MIDDLEWARE_CLASSES`` matters. See `Order of MIDDLEWARE_CLASSES`_
-below.)
+.. note::
+
+    No, that's not a typo: the "update" middleware must be first in the list,
+    and the "fetch" middleware must be last. The details are a bit obscure, but
+    see `Order of MIDDLEWARE_CLASSES`_ below if you'd like the full story.
 
 Then, add the following required settings to your Django settings file:
 
@@ -258,10 +266,9 @@ parameters. Optionally, if the ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting is
 will be cached. This is a simple and effective way of disabling caching for any
 user-specific pages (include Django's admin interface). Note that if you use
 ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY``, you should make sure you've activated
-``AuthenticationMiddleware`` and that ``AuthenticationMiddleware`` appears
-before ``CacheMiddleware`` in your ``MIDDLEWARE_CLASSES``.
+``AuthenticationMiddleware``.
 
-Additionally, ``CacheMiddleware`` automatically sets a few headers in each
+Additionally, the cache middleware automatically sets a few headers in each
 ``HttpResponse``:
 
 * Sets the ``Last-Modified`` header to the current date/time when a fresh
@@ -627,16 +634,24 @@ apps' performance:
 Order of MIDDLEWARE_CLASSES
 ===========================
 
-If you use ``CacheMiddleware``, it's important to put it in the right place
-within the ``MIDDLEWARE_CLASSES`` setting, because the cache middleware needs
-to know which headers by which to vary the cache storage. Middleware always
-adds something to the ``Vary`` response header when it can.
+If you use caching middlewaare, it's important to put each half in the right
+place within the ``MIDDLEWARE_CLASSES`` setting. That's because the cache
+middleware needs to know which headers by which to vary the cache storage.
+Middleware always adds something to the ``Vary`` response header when it can.
 
-Put the ``CacheMiddleware`` *before* any other middleware that might add
-something to the ``Vary`` header (response middleware is applied in reverse
-order). The following middleware modules do so:
+``UpdateCacheMiddleware`` runs during the response phase, where middleware is
+run in reverse order, so an item at the top of the list runs *last* during the
+response phase. Thus, you need to make sure that ``UpdateCacheMiddleware``
+appears *before* any other middleware that might add something to the ``Vary``
+header. The following middleware modules do so:
 
     * ``SessionMiddleware`` adds ``Cookie``
     * ``GZipMiddleware`` adds ``Accept-Encoding``
     * ``LocaleMiddleware`` adds ``Accept-Language``
+    
+``FetchFromCacheMiddleware``, on the other hand, runs during the request phase,
+where middleware is applied first-to-last, so an item at the top of the list
+runs *first* during the request phase. The ``FetchFromCacheMiddleware`` also
+needs to run after other middleware updates the ``Vary`` header, so
+``FetchFromCacheMiddleware`` must be *after* any item that does so.