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.