Merge pull request #32 from ddeboer/docs

Improve docs
FriendsOfSymfony · Mar 4, 2014 · 68dd4c2 · 68dd4c2
2 parents 0eae815 + e2f4b53
commit 68dd4c2
Show file tree

Hide file tree

Showing 13 changed files with 624 additions and 329 deletions.
diff --git a/README.md b/README.md
@@ -4,24 +4,25 @@ FOSHttpCache
 [![Scrutinizer Quality Score](https://scrutinizer-ci.com/g/ddeboer/FOSHttpCache/badges/quality-score.png?s=5b808e92306a54228a81378ec20a47bb5313a5c7)](https://scrutinizer-ci.com/g/ddeboer/FOSHttpCache/)
 [![Code Coverage](https://scrutinizer-ci.com/g/ddeboer/FOSHttpCache/badges/coverage.png?s=f9f57d6b28285f38782b38a08b1dbdb24901a764)](https://scrutinizer-ci.com/g/ddeboer/FOSHttpCache/)
 
-
 Introduction
 ------------
 
 This library integrates your PHP applications with HTTP caching proxies such as Varnish.
 Use this library to send invalidation requests from your application to the caching proxy
 and to test your caching and invalidation code against a Varnish setup.
 
-If you use Symfony2, you want to look at the [FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle)
-which provides the invalidator as a service to Symfony2, along with a couple of
-other useful Symfony2 specific features to help with caching and caching proxies.
+If you use Symfony2, have a look at the
+[FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle).
+The bundle provides the invalidator as a service, along with a number of
+Symfony2-specific features to help with caching and caching proxies.
 
 Features
 --------
 
 * Send [cache invalidation requests](doc/cache-invalidator.md) with minimal impact on performance.
 * Use the built-in support for [Varnish](doc/varnish.md) or easily implement your own caching proxy client.
 * [Test your application](doc/testing-your-application.md) against your Varnish setup.
+* This library is compatible with [HHVM](http://www.hhvm.com/blog/).
 
 Documentation
 -------------

diff --git a/doc/cache-invalidator.md b/doc/cache-invalidator.md
@@ -1,151 +1,153 @@
 The Cache Invalidator
-=================
+=====================
 
-Use the CacheInvalidator to explicitly invalidate or refresh paths, URLs or
-headers.
+Use the cache invalidator to invalidate or refresh paths, URLs and headers.
+It is the invalidator that you will probably use most when interacting with
+the library. 
 
 * [Setup](#setup)
-* [Invalidating paths and URLs](#invalidating-paths-and-urls)
-* [Refreshing paths and URLs](#refreshing-paths-and-urls)
+* [Invalidating Paths and URLs](#invalidating-paths-and-urls)
+* [Refreshing Paths and URLs](#refreshing-paths-and-urls)
 * [Invalidating with a Regular Expression](#invalidating-with-a-regular-expression)
+  * [URL, Content Type and Hostname](#urls-content-type-and-hostname)
+  * [Any Header](#any-header)
 * [Tags](#tags)
+  * [Custom Tags Header](#custom-tags-header)
 * [Flushing](#flushing)
 * [Error handling](#error-handling)
+  * [Logging errors](#logging-errors)
 
 Setup
 -----
 
-The CacheInvalidator wraps a low-level caching proxy client. To construct the
-invalidator, pass the proxy client to it. For instance, when using [Varnish](varnish.md):
+Create the cache invalidator by passing a [proxy client](proxy-clients.md) as
+an [adapter](http://en.wikipedia.org/wiki/Adapter_pattern):
 
 ```php
-use FOS\HttpCache\Invalidation\Varnish;
 use FOS\HttpCache\CacheInvalidator;
+use FOS\HttpCache\Invalidation;
 
-$varnish = new Varnish(...);
-$cacheInvalidator = new CacheInvalidator($varnish);
+$client = new Invalidation\Varnish();
+// or
+$client = new Invalidation\Nginx();
+
+$cacheInvalidator = new CacheInvalidator($client);
 ```
 
-Invalidating paths and URLs
+Invalidating Paths and URLs
 ---------------------------
 
-Make sure to configure your proxy for purging first.
-(See [varnish](varnish.md#purge).)
+Make sure to [configure your proxy](proxy-configuration.md) for purging first.
 
 Invalidate a path:
 
 ```php
-$cacheInvalidator->invalidatePath('/users');
+$cacheInvalidator->invalidatePath('/users')
+    ->flush()
+;
 ```
 
-Invalidate an URL:
+See below for the [flush](#flushing) method.
+
+Invalidate a URL:
+
 ```php
-$cacheInvalidator->invalidatePath('http://www.example.com/users');
+$cacheInvalidator->invalidatePath('http://www.example.com/users')->flush();
 ```
 
-Refreshing paths and URLs
+Refreshing Paths and URLs
 -------------------------
 
-Make sure to configure your proxy for refreshing first.
-(See [varnish](varnish.md#refresh).)
+Make sure to [configure your proxy](proxy-configuration.md) for refreshing
+first.
 
 Refresh a path:
 
 ```php
-$cacheInvalidator->refreshPath('/users');
+$cacheInvalidator->refreshPath('/users')->flush();
 ```
 
-Refresh an URL:
+Refresh a URL:
 
 ```php
-$cacheInvalidator->refreshPath('http://www.example.com/users');
+$cacheInvalidator->refreshPath('http://www.example.com/users')->flush();
 ```
 
-Invalidating a path with a Regular Expression
----------------------------------------------
+Invalidating With a Regular Expression
+--------------------------------------
+
+Make sure to [configure your proxy](proxy-configuration.md) for banning first.
 
-Make sure to configure your proxy for regular expressions first.
-(See [varnish ban](varnish.md#ban).)
+### URL, Content Type and Hostname
 
 You can invalidate all URLs matching a regular expression by using the
 `invalidateRegex` method. You can further limit the cache entries to invalidate
-with a regular expression for the content type and/or the host name.
+with a regular expression for the content type and/or the application hostname.
 
-For instance, to invalidate all .css files for all host names handled by this
+For instance, to invalidate all .css files for all hostnames handled by this
 caching proxy:
 
 ```php
-$cacheInvalidator->invalidateRegex('.*css$');
+$cacheInvalidator->invalidateRegex('.*css$')->flush();
 ```
 
-To invalidate all png files for host example.com:
+To invalidate all .png files for host example.com:
 
 ```php
-$cacheInvalidator->invalidateRegex('.*', 'image/png', array('example.com'));
+$cacheInvalidator
+    ->invalidateRegex('.*', 'image/png', array('example.com'))
+    ->flush()
+;
 ```
 
-If you need other criteria than path, content type and hosts, use the
-`invalidate` method.
-
-Invalidating requests with any headers
---------------------------------------
+### Any Header
 
 You can also invalidate the cache based on any headers. If you use non-default
-headers, make sure to configure your proxy accordingly to have them taken into
-account. (See [varnish ban](varnish.md#ban).)
+headers, make sure to [configure your proxy accordingly](proxy-configuration.md)
+to have them taken into account.
 
 Cache client implementations should fill up the headers to at least have the
 default headers always present to simplify the cache configuration rules.
 
 To invalidate on a custom header X-My-Header, you would do:
 
 ```php
-$cacheInvalidator->invalidate(array('X-My-Header' => 'my-value'));
-```
-
-Fluent interface
-----------------
-
-The cache invalidator offers a fluent interface:
-
-```php
-$cacheInvalidator
-    ->invalidatePath('/bad/guys')
-    ->invalidatePath('/good/guys')
-    ->refreshPath('/')
-;
+$cacheInvalidator->invalidate(array('X-My-Header' => 'my-value'))->flush();
 ```
 
 Tags
 ----
 
-Make sure to [configure your proxy for tagging](varnish.md#tagging) first.
-The examples in this section assume you left the `tagsHeader` unchanged. You
-can call `CacheInvalidator::setTagsHeader` to change the HTTP header used to
-identify tags.
+Make sure to [configure your proxy for tagging](proxy-configuration.md) first.
 
 You will have to make sure your web application adds the correct tags on all
-responses. The [HttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle)
-provides means to help you with this, but without Symfony there is no generic
-way to do this.
+responses by setting the `X-Cache-Tags` header. The
+[FOSHttpCacheBundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle)
+does this for you when you’re using Symfony.
 
-Assume you sent 3 responses:
+Assume you sent four responses:
 
-* /one had the header `X-Cache-Tags: tag-one`
-* /two had the header `X-Cache-Tags: tag-two, group-a`
-* /three had the header `X-Cache-Tags: tag-three, group-a`
-* /four had the header `X-Cache-Tags: tag-four, group-b`
+* `/one` had the header `X-Cache-Tags: tag-one`
+* `/two` had the header `X-Cache-Tags: tag-two, group-a`
+* `/three` had the header `X-Cache-Tags: tag-three, group-a`
+* `/four` had the header `X-Cache-Tags: tag-four, group-b`
 
 You can now invalidate some URLs using tags:
 
 ```php
-$cacheInvalidator->invalidateTags(array('group-a', 'tag-four'));
+$cacheInvalidator->invalidateTags(array('group-a', 'tag-four'))->flush();
 ```
 
-This will ban all requests having either the tag group-a OR tag-four. In the
-above example, this will invalidate "/two", "/three" and "/four". Only "/one"
+This will ban all requests having either the tag `group-a` /or/ `tag-four`. In
+the above example, this will invalidate `/two`, `/three` and `/four`. Only `/one`
 will stay in the cache.
 
+### Custom Tags Header
+
+Tagging uses a custom HTTP header to identify tags. You can change the default
+header `X-Cache-Tags` by calling `setTagsHeader()`. Make sure to reflect this
+change in your [caching proxy configuration](varnish-configuration.md#tagging).
+
 Flushing
 --------
 
@@ -160,16 +162,13 @@ $cacheInvalidator
 ;
 ```
 
-Note: When using the Symfony Bundle, the cache invalidator is automatically
-flushed. When using the Bundle, you only need to manually call flush when not
-in a request context. (E.g. from a command.)
+Try delaying flush until after the response has been sent to the client’s
+browser. This keeps the performance impact of sending invalidation requests to
+a minimum.
 
-To keep the performance impact of sending invalidation requests to a minimum,
-make sure to only flush /after/ the response has been sent to the client’s
-browser.
-
-The Varnish client also sends all invalidation requests in parallel to further
-reduce the time used by invalidation.
+When using the [Symfony bundle](https://github.com/FriendsOfSymfony/FOSHttpCacheBundle),
+you don’t have to call `flush()`, as the bundle flushes the invalidator for you
+after the response has been sent.
 
 Error handling
 --------------
@@ -184,6 +183,27 @@ These exception are of two types:
 * `\FOS\HttpCache\ProxyResponseException` when the caching proxy returns an
    error response, such as 403 Forbidden.
 
+So, to catch exceptions:
+
+```php
+use FOS\HttpCache\Exception\ExceptionCollection;
+
+$cacheInvalidator
+    ->invalidatePath('/users');
+
+try {
+    $cacheInvalidator->flush();
+} catch (ExceptionCollection $exceptions) {
+    // The first exception that occurred
+    var_dump($exceptions->getFirst());
+
+    // Iterate over the exception collection
+    foreach ($exceptions as $exception) {
+        var_dump($exception);
+    }
+}
+```
+
 ### Logging errors
 
 You can log any exceptions in the following way. First construct a logger that
@@ -193,16 +213,16 @@ implements `\Psr\Log\LoggerInterface`. For instance, when using
 ```php
 use Monolog\Logger;
 
-$logger = new Logger(...);
-$logger->pushHandler(...);
+$monolog = new Logger(...);
+$monolog->pushHandler(...);
 ```
 
 Then add the logger as a subscriber to the cache invalidator:
 
 ```php
 use FOS\HttpCache\EventListener\LogSubscriber;
 
-$subscriber = new LogSubscriber($logger);
+$subscriber = new LogSubscriber($monolog);
 $cacheInvalidator->addSubscriber($subscriber);
 ```
 
@@ -219,4 +239,4 @@ try {
 } catch (ExceptionCollection $exceptions) {
     // At least one failed request, check your logs!
 }
-```
+```