Update proxy client chapter

Author: ddeboer

Resources/doc/reference/configuration/invalidation.rst

@@ -52,9 +52,8 @@ invalidated. By default, any request parameters that are not part of the
 invalidated route are ignored. Set ``ignore_extra_params`` to ``false``
 to set those parameters anyway.
 
-Some more explanation.
-
-Assume route ``villain_edit`` resolves to ``/villain/{id}/edit``.
+A more detailed explanation:
+assume route ``villain_edit`` resolves to ``/villain/{id}/edit``.
 When a client successfully edits the details for villain with id 123 (at
 ``/villain/123/edit``), the index of villains (at ``/villains``) can be
 invalidated (purged) without trouble. But which villain details page should we

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

@@ -1,70 +1,89 @@
 Proxy Client Configuration
 ==========================
 
-Usually, your application will interact with the caching proxy through the
-:doc:`Cache Manager </reference/cache-manager>`. You need to configure a proxy
-client for the cache manager to work. The proxy client is also available as a
+The proxy client sends invalidation requests to your caching proxy. It must be
+configured for the :doc:`Cache Manager </reference/cache-manager>` to work,
+which wraps the proxy client and is the usual entry point for application
+interaction with the caching proxy. The proxy client is also available as a
 service (``fos_http_cache.proxy_client``) that you can use directly.
 
-.. glossary::
+Varnish
+-------
 
-    ``servers``
-        Comma-separated list of IP addresses or host names of your
-        caching proxy servers. The port those servers will be contacted
-        defaults to 6081, you can specify a different port with ``:<port>``.
+.. code-block:: yaml
+
+    # app/config/config.yml
+    fos_http_cache:
+        proxy_client:
+            varnish:
+                servers: 123.123.123.1:6060, 123.123.123.2
+                base_url: yourwebsite.com
+
+servers
+"""""""
 
-    ``base_url``
-        This must match the web host name clients are using when connecting
-        to the caching proxy. Optionally can contain a base path to your
-        application. Used for invalidation with paths.
+**type**: ``array``
+
+Comma-separated list of IP addresses or host names of your
+caching proxy servers. The port those servers will be contacted
+defaults to 6081, you can specify a different port with ``:<port>``.
+
+base_url
+""""""""
+
+**type**: ``string``
+
+This must match the web host name clients are using when connecting
+to the caching proxy. Optionally can contain a base path to your
+application. Used for invalidation with paths.
 
 .. warning::
 
     Double-check ``base_url``, for if it is mistyped, no content will be
     invalidated.
 
-.. todo::
-
-    **TODO: MOVE** When using ESI, you will want to purge individual fragments. To generate the
-    corresponding ``_internal`` route, inject the ``http_kernel`` into your controller and
-    use HttpKernel::generateInternalUri with the parameters as in the twig
-    ``render`` tag.
+See the :ref:`FOSHttpCache library docs <foshttpcache:varnish configuration>`
+on how to configure Varnish.
 
-Configure for Varnish
----------------------
+Nginx
+-----
 
 .. code-block:: yaml
 
     # app/config/config.yml
     fos_http_cache:
-      proxy_client:
-        varnish:
-          servers: 123.123.123.1:6060, 123.123.123.2
-          base_url: yourwebsite.com
+        proxy_client:
+            nginx:
+                servers: 123.123.123.1:6060, 123.123.123.2
+                base_url: yourwebsite.com
+                purge_location: /purge
 
-Configure for Nginx
--------------------
+For ``servers`` and ``base_url``, see above.
 
-.. code-block:: yaml
+purge_location
+""""""""""""""
 
-    # app/config/config.yml
-    fos_http_cache:
-      proxy_client:
-        nginx:
-          servers: 123.123.123.1:6060, 123.123.123.2
-          base_url: yourwebsite.com
-          purge_location: /purge
-
-The options are the same as for Varnish with the addition of the
-``purge_location`` used for the "different location" concept of Nginx.
-
-.. tip::
-
-    Although its not a common scenario, you can **use Nginx and Varnish in
-    parallel**. If you need to cache and invalidate pages in both, you can
-    configure both in this bundle. The CacheManager will however only use the
-    default client. You can set the default with
-    ``fos_http_client.proxy_client.default: nginx`` (resp. ``varnish``).
+**type**: ``string``
+
+Separate location that purge requests will be sent to.
+
+See the :ref:`FOSHttpCache library docs <foshttpcache:nginx configuration>`
+on how to configure Nginx.
+
+default
+-------
+
+**type**: ``enum`` **options**: ``varnish``, ``nginx``
+
+.. code-block:: yaml
+fos_http_cache:
+        proxy_client:
+            default: varnish
+
+The default proxy client that will be used by the cache manager.
+You can *use Nginx and Varnish in parallel*. If you need to cache and
+invalidate pages in both, you can configure both in this bundle.
+The cache manager however will only use the default client.
 
 Custom Guzzle Client
 --------------------