diff --git a/Resources/doc/features/tagging.rst b/Resources/doc/features/tagging.rst index c0dd5c7a..a4fcb858 100644 --- a/Resources/doc/features/tagging.rst +++ b/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 `. -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 ` 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:: diff --git a/Resources/doc/reference/configuration/proxy-client.rst b/Resources/doc/reference/configuration/proxy-client.rst index c2e0f19b..705e398e 100644 --- a/Resources/doc/reference/configuration/proxy-client.rst +++ b/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 diff --git a/Resources/doc/reference/configuration/tags.rst b/Resources/doc/reference/configuration/tags.rst index 9951e447..5cf7f8a9 100644 --- a/Resources/doc/reference/configuration/tags.rst +++ b/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 `, -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 `, + 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. \ No newline at end of file +You can combine ``tags`` and ``tag_expression`` in one rule. diff --git a/Resources/doc/testing.rst b/Resources/doc/testing.rst index 2dda0fe5..f8261fc7 100644 --- a/Resources/doc/testing.rst +++ b/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 `. 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 `. + +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 ` - on how to write integration tests that validate your caching code and - configuration against a caching proxy.