Caching Proxy Clients

This library ships with clients for the Varnish, NGINX and Symfony built-in caching proxies. You can use the clients either wrapped by the cache invalidator (recommended), or directly for low-level access to invalidation functionality.

Setup

Varnish Client

At minimum, supply an array containing IPs or hostnames of the Varnish servers that you want to send invalidation requests to. Make sure to include the port Varnish runs on if it is not port 80:

use FOS\HttpCache\ProxyClient\Varnish;

$servers = array('10.0.0.1', '10.0.0.2:6081'); // Port 80 assumed for 10.0.0.1
$varnish = new Varnish($servers);

This is sufficient for invalidating absolute URLs. If you also wish to invalidate relative paths, supply the hostname (or base URL) where your website is available as the second parameter:

$varnish = new Varnish($servers, 'my-cool-app.com');

Again, if you access your web application on a port other than 80, make sure to include that port in the base URL:

$varnish = new Varnish($servers, 'my-cool-app.com:8080');

Note

To make invalidation work, you need to configure Varnish accordingly.

NGINX Client

At minimum, supply an array containing IPs or hostnames of the NGINX servers that you want to send invalidation requests to. Make sure to include the port NGINX runs on if it is not the default:

use FOS\HttpCache\ProxyClient\Nginx;

$servers = array('10.0.0.1', '10.0.0.2:8088'); // Port 80 assumed for 10.0.0.1
$nginx = new Nginx($servers);

This is sufficient for invalidating absolute URLs. If you also wish to invalidate relative paths, supply the hostname (or base URL) where your website is available as the second parameter:

$nginx = new Nginx($servers, 'my-cool-app.com');

If you have configured NGINX to support purge requests at a separate location, supply that location to the class as the third parameter:

$nginx = new Nginx($servers, 'my-cool-app.com', '/purge');

Note

To use the client, you need to configure NGINX accordingly.

Symfony Client

At minimum, supply an array containing IPs or hostnames of your web servers running Symfony. Provide the direct access to the web server without any other proxies that might block invalidation requests. Make sure to include the port the web server runs on if it is not the default:

use FOS\HttpCache\ProxyClient\Symfony;

$servers = array('10.0.0.1', '10.0.0.2:8088'); // Port 80 assumed for 10.0.0.1
$client = new Symfony($servers);

This is sufficient for invalidating absolute URLs. If you also wish to invalidate relative paths, supply the hostname (or base URL) where your website is available as the second parameter:

$client = new Symfony($servers, 'my-cool-app.com');

Note

To make invalidation work, you need to use the EventDispatchingHttpCache.

Using the Clients

Each client is an implementation of ProxyClientInterface. All other interfaces, PurgeInterface, RefreshInterface and BanInterface extend this ProxyClientInterface. So each client implements at least one of the three invalidation methods depending on the caching proxy’s abilities.

The ProxyClientInterface has one method: flush(). After collecting invalidation requests, flush() needs to be called to actually send the requests to the caching proxy. This is on purpose: this way, we can send all requests together, reducing the performance impact of sending invalidation requests.

Supported invalidation methods

Client	Purge	Refresh	Ban
Varnish	✓	✓	✓
NGINX	✓	✓
Symfony Cache	✓	✓

Purge

If the caching proxy understands purge requests, its client should implement PurgeInterface. Use the purge($url) method to purge one specific URL. The URL can be either an absolute URL or a relative path:

$client
    ->purge('http://my-app.com/some/path')
    ->purge('/other/path')
    ->flush()
;

You can specify HTTP headers as the second argument to purge(). For instance:

$client
    ->purge('/some/path', array('X-Foo' => 'bar')
    ->flush()
;

Please note that purge will invalidate all variants, so you do not have to send any headers that you vary on, such as Accept.

This allows you to pass headers that are different between purge requests. If you want to add a header to all purge requests, such as Authorization, use a custom Guzzle client instead.

Refresh

If the caching proxy understands refresh requests, its client should implement RefreshInterface. Use refresh() to refresh one specific URL. The URL can be either an absolute URL or a relative path:

$client
    ->refresh('http://my-app.com/some/path')
    ->refresh('other/path')
    ->flush()
;

You can specify HTTP headers as the second argument to refresh(). For instance, to only refresh the JSON representation of an URL:

$client
    ->refresh('/some/path', array('Accept' => 'application/json')
    ->flush()
;

Ban

If the caching proxy understands ban requests, its client should implement BanInterface.

You can invalidate all URLs matching a regular expression by using the banPath($path, $contentType, $hosts) method. It accepts a regular expression for the path to invalidate and an optional content type regular expression and list of application hostnames.

For instance, to ban all .png files on all application hosts:

$client->banPath('.*png$');

To ban all HTML URLs that begin with /articles/:

$client->banPath('/articles/.*', 'text/html');

By default, URLs will be banned on all application hosts. You can limit this by specifying a host header:

$client->banPath('*.png$', null, '^www.example.com$');

If you want to go beyond banning combinations of path, content type and hostname, use the ban(array $headers) method. This method allows you to specify any combination of headers that should be banned. For instance, when using the Varnish client:

use FOS\HttpCache\ProxyClient\Varnish;

$varnish->ban(array(
    Varnish::HTTP_HEADER_URL   => '.*\.png$',
    Varnish::HTTP_HEADER_HOST  => '.*example\.com',
    Varnish::HTTP_HEADER_CACHE => 'my-tag',
));

Make sure to add any headers that you want to ban on to your proxy configuration.

Custom Guzzle Client

By default, the proxy clients instantiate a Guzzle client to communicate with the caching proxy. If you need to customize the requests, for example to send a basic authentication header, you can inject a custom Guzzle client:

use FOS\HttpCache\ProxyClient\Varnish;
use Guzzle\Http\Client;

$client = new Client();
$client->setDefaultOption('auth', array('username', 'password', 'Digest'));

$servers = array('10.0.0.1');
$varnish = new Varnish($servers, '/baseUrl', $client);

The Symfony client accepts a guzzle client as the 3rd parameter as well, NGINX accepts it as 4th parameter.