Merge pull request #375 from FriendsOfSymfony/improve-tags-and-noop-doc

improve documentation for tags and noop client

Author: dbu

Resources/doc/features/tagging.rst

@@ -47,8 +47,8 @@ invalidations and flushes them. As with other invalidation operations, tag
 invalidation requests are flushed to the caching proxy
 :ref:`after the response has been sent <flushing>`.
 
-Tagging from Code
-~~~~~~~~~~~~~~~~~
+Tagging and Invalidating from PHP Code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To add tags to responses, inject the ``ResponseTagger`` (service
 ``fos_http_cache.http.symfony_response_tagger``) and use ``addTags($tags)`` to
@@ -116,8 +116,8 @@ with the response tagger and can also be mixed with the other methods:
     Tag invalidation from twig would be a strange architecture and is therefore
     not supported.
 
-Tagging with Configuration Rules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Tagging and Invalidating with Configuration Rules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Alternatively, you can :doc:`configure rules </reference/configuration/tags>`
 for setting and invalidating tags:
@@ -137,8 +137,8 @@ Now if a :term:`safe` request matches the criteria under ``match``, the response
 will be tagged with ``news``. When an unsafe request matches, the tag ``news``
 will be invalidated.
 
-Tagging with Controller Annotations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Tagging and Invalidating with Controller Annotations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Add the ``@Tag`` annotations to your controllers to set and invalidate tags::
 

Resources/doc/reference/configuration/proxy-client.rst

@@ -145,20 +145,26 @@ symfony
 
 For ``servers`` and ``base_url``, see above.
 
+.. _configuration_noop_proxy_client:
+
 noop
 ----
 
 .. code-block:: yaml
 
-    # app/config/config.yml
+    # app/config/config_test.yml
     fos_http_cache:
         proxy_client:
+            default: noop
             noop: ~
 
+This proxy client supports all invalidation methods, but implements doing
+nothing (hence the name "no operation" client). This can be useful for testing.
+
 default
 -------
 
-**type**: ``enum`` **options**: ``varnish``, ``nginx``, ``symfony``
+**type**: ``enum`` **options**: ``varnish``, ``nginx``, ``symfony``, ``noop``
 
 .. code-block:: yaml
 

Resources/doc/reference/configuration/tags.rst

@@ -7,9 +7,17 @@ for an introduction.
 
 .. include:: /includes/enabled.rst
 
-If you use a :doc:`proxy client that does not support banning </features/tagging>`,
-cache tagging is not possible. If you leave ``enabled`` on ``auto``, tagging will
-be deactivated.
+.. note::
+
+    If you use a :doc:`proxy client that does not support tag invalidation </features/tagging>`,
+    cache tagging is not possible.
+
+    If you leave ``enabled`` on ``auto``, tagging will only be activated when
+    using the varnish client.
+
+    When using the noop proxy client or a custom service, ``auto`` will also
+    lead to tagging being disabled. If you want to use tagging in one of those
+    cases, you need to explicitly enable tagging.
 
 Enables tag annotations and rules. If you want to use tagging, it is recommended
 that you set this to ``true`` so you are notified of missing dependencies and
@@ -115,4 +123,4 @@ tag ``articles-123`` with the following configuration:
 The expression has access to all request attributes and the request itself
 under the name ``request``.
 
-You can combine ``tags`` and ``tag_expression`` in one rule.
+You can combine ``tags`` and ``tag_expression`` in one rule.

Resources/doc/testing.rst

@@ -1,8 +1,19 @@
 Testing
 =======
 
-Testing the Bundle
-------------------
+Testing your Application
+------------------------
+
+If you do not want to test caching proxy interactions during testing, you can
+:ref:`use the Noop proxy client <configuration_noop_proxy_client>`. This
+client implements all invalidation features but does nothing at all.
+
+If you want to write integration tests that validate your caching code and
+configuration against the actual caching proxy, have a look at the
+:ref:`FOSHttpCache library’s docs <foshttpcache:testing your application>`.
+
+Testing the FOSHttpCacheBundle
+------------------------------
 
 To run this bundle’s tests, clone the repository, install vendors, and invoke
 PHPUnit:
@@ -13,9 +24,3 @@ PHPUnit:
     $ cd FOSHttpCacheBundle
     $ composer install
     $ vendor/bin/phpunit
-
-.. tip::
-
-    See the :ref:`FOSHttpCache library’s docs <foshttpcache:testing your application>`
-    on how to write integration tests that validate your caching code and
-    configuration against a caching proxy.