FOSHttpCacheBundle¶

Cache Manager¶

To invalidate single paths, URLs and routes manually, use the invalidatePath($path, $headers) and invalidateRoute($route, $params, $headers) methods on the cache manager:

$cacheManager = $container->get('fos_http_cache.cache_manager');

// Invalidate a path
$cacheManager->invalidatePath('/users')->flush();

// Invalidate a URL
$cacheManager->invalidatePath('http://www.example.com/users')->flush();

// Invalidate a route
$cacheManager->invalidateRoute('user_details', array('id' => 123))->flush();

// Invalidate a route or path with headers
$cacheManager->invalidatePath('/users', array('X-Foo' => 'bar'))->flush();
$cacheManager->invalidateRoute('user_details', array('id' => 123), array('X-Foo' => 'bar'))->flush();

To invalidate multiple representations matching a regular expression, call invalidateRegex($path, $contentType, $hosts):

$cacheManager->invalidateRegex('.*', 'image/png', array('example.com'));

To refresh paths and routes, you can use refreshPath($path, $headers) and refreshRoute($route, $params, $headers) in a similar manner. See The Cache Manager for more information.

Configuration¶

You can add invalidation rules to your application configuration:

# app/config/config.yml
fos_http_cache:
    invalidation:
        rules:
            -
                match:
                    attributes:
                        _route: "villain_edit|villain_delete"
                routes:
                    villains_index: ~    # e.g., /villains
                    villain_details: ~   # e.g., /villain/{id}

Now when a request to either route villain_edit or route villain_delete returns a successful response, both routes villains_index and villain_details will be purged. See the invalidation configuration reference.

Annotations¶

Set the @InvalidatePath and @InvalidateRoute annotations to trigger invalidation from your controllers:

use FOS\HttpCacheBundle\Configuration\InvalidatePath;

/**
 * @InvalidatePath("/articles")
 * @InvalidatePath("/articles/latest")
 * @InvalidateRoute("overview", params={"type" = "latest"})")
 * @InvalidateRoute("detail", params={"id" = {"expression"="id"}})")
 */
public function editAction($id)
{
}

See the Annotations reference.

Console Commands¶

This bundle provides commands to trigger cache invalidation from the command line. You could also send invalidation requests with a command line tool like curl or, in the case of varnish, varnishadm. But the commands simplify the task and will automatically talk to all configured cache instances.

• fos:httpcache:invalidate:path accepts one or more paths and invalidates each of them. See invalidatePath().
• fos:httpcache:refresh:path accepts one or more paths and refreshes each of them. See refreshPath() and refreshRoute().
• fos:httpcache:invalidate:regex expects a regular expression and invalidates all cache entries matching that expression. To invalidate your entire cache, you can specify . (dot) which will match everything. See invalidatePath().
• fos:httpcache:invalidate:tag accepts one or more tags and invalidates all cache entries matching any of those tags. See Tagging.

If you need more complex interaction with the cache manager, best write your own commands and use the cache manager to implement your specific logic.

Basic Configuration¶

First configure your proxy for tagging. Then enable tagging in your application configuration:

fos_http_cache:
    tags:
        enabled: true

For more information, see tags.

Setting and Invalidating Tags¶

You can tag responses in different ways: with the tag handler from PHP or with a twig function, from configuration or using annotations on controller actions.

use FOS\HttpCacheBundle\Handler\TagHandler;

class NewsController
{
    /**
     * @var TagHandler
     */
    private $tagHandler;

    public function articleAction($id)
    {
        $this->tagHandler->addTags(array('news', 'news-' . $id));

        // ...
    }
}

class NewsController
{
    // ...

    public function editAction($id)
    {
        // ...

        $this->tagHandler->invalidateTags(array('news-' . $id));

        // ...
    }
}

{# template.html.twig #}
{{ fos_httpcache_tag('mytag') }}
{{ fos_httpcache_tag(['tag-one', 'tag-two']) }}

// app/config/config.yml
fos_http_cache:
    tags:
        rules:
            -
                match:
                    path: ^/news/article
                tags: [news]

use FOS\HttpCacheBundle\Configuration\Tag;

class NewsController
{
    /**
     * @Tag("news", expression="'news-'~id")
     */
    public function articleAction($id)
    {
        // Assume $id equals 123
    }
}

How It Works¶

These five steps resemble the Overview in the FOSHttpCache documentation.

1. A client requests /foo.
2. The caching proxy receives the request and holds it. It first sends a hash request to the context hash route.
3. The application receives the hash request. An event listener (UserContextListener) aborts the request immediately after the Symfony2 firewall was applied. The application calculates the hash (HashGenerator) and then sends a response with the hash in a custom header (X-User-Context-Hash by default).
4. The caching proxy receives the hash response, copies the hash header to the client’s original request for /foo and restarts that request.
5. If the response to /foo should differ per user context, the application sets a Vary: X-User-Context-Hash header. The appropriate user context dependent representation of /foo will then be returned to the client.

Configuration¶

First configure your caching proxy. Then configure Symfony for handling hash lookups. The minimal steps are described below, see the reference for more details.

You need to configure a route for the context hash. It does not specify any controller, as the request listener will abort the request right after the firewall has been applied, but the route definition must exist. Use the same path as you specified in the caching proxy and make sure that this path is allowed for anonymous users and covered by your firewall configuration:

# app/config/routing.yml
user_context_hash:
    path: /_fos_user_context_hash

If your access rules limit the whole site to logged in users, make sure to handle the user context URL like the login page:

# app/config/security.yml
access_control:
    - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY }
    - { path: ^/_fos_user_context_hash, roles: [IS_AUTHENTICATED_ANONYMOUSLY] }
    - { path: ^/, roles: ROLE_USER }

Finally, enable the listener with the default settings:

# app/config/config.yml
fos_http_cache:
    user_context:
        enabled: true

Generating Hashes¶

When a context hash request is received, the HashGenerator is used to build the context information. The generator does so by calling on one or more context providers.

The bundle includes a simple role_provider that determines the hash from the user’s roles. To enable it:

# app/config/config.yml
fos_http_cache:
    user_context:
        role_provider: true

Alternatively, you can create a custom context provider.

Caching Hash Responses¶

To improve User Context Caching performance, you should cache the hash responses. You can do so by configuring hash_cache_ttl.

ProxyTestCase¶

If you wish to test your application caching and invalidation strategies against a live Varnish or Nginx instance, extend your test classes from ProxyTestCase. ProxyTestCase is an abstract base test class that in its turn extends Symfony’s WebTestCase. It offers some convenience methods for cache testing:

class YourTest extends ProxyTestCase
{
    public function testCachingHeaders()
    {
        // Retrieve an URL from your application
        $response = $this->getResponse('/your/page');

        // Assert the response was a cache miss (came from the backend
        // application)
        $this->assertMiss($response);

        // Assume the URL /your/page sets caching headers. If we retrieve
        // it again, we should have a cache hit (response delivered by the
        // caching proxy):
        $response = $this->getResponse('/your/page');
        $this->assertHit($response);
    }
}

Controlling Your Caching Proxy¶

You can also use ProxyTestCase to control your caching proxy. First configure the proxy server:

// app/config/config_test.yml
fos_http_cache:
    test:
        proxy_server:
            varnish:
                binary: /usr/sbin/varnishd
                port: 8080
                config_file: /etc/varnish/your-config.vcl

The custom @clearCache PHPUnit annotation will start the proxy server (if it was not yet running) and clear any previously cached content. This enables you to write isolated test cases:

use FOS\HttpCacheBundle\Test\ProxyTestCase;

class YourTest extends ProxyTestCase
{
    /**
     * @clearCache
     */
    public function testMiss()
    {
        // We can be sure this is a miss, because even if the content was
        // cached before, it has been cleared from the caching proxy.
        $this->assertMiss($this->getResponse('/your/page'));
    }
}

You can annotate single test methods as well as classes with @clearCache. An annotated test class will restart and clear the caching proxy for each test case contained in the class.

You can also manually control your caching proxy:

use FOS\HttpCacheBundle\Test\ProxyTestCase;

class YourTest extends ProxyTestCase
{
    public function testMiss()
    {
        // Start caching proxy
        $this->getProxy()->start();

        // Clear proxy cache
        $this->getProxy()->clear();

        $this->assertMiss($this->getResponse('/your/page'));

        // Stop caching proxy
        $this->getProxy()->stop();
    }
}

Extending the correct HttpCache¶

Instead of extending Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache, your AppCache should extend FOS\HttpCacheBundle\SymfonyCache\EventDispatchingHttpCache:

require_once __DIR__.'/AppKernel.php';

use FOS\HttpCacheBundle\SymfonyCache\EventDispatchingHttpCache;

class AppCache extends EventDispatchingHttpCache
{
}

By default, the event dispatching cache kernel registers all event listeners it knows about. You can disable listeners, or customize how they are instantiated.

If you do not need all listeners, or need to register some yourself to customize their behavior, overwrite getOptions and return the right bitmap in fos_default_subscribers. Use the constants provided by the EventDispatchingHttpCache:

public function getOptions()
{
    return array(
        'fos_default_subscribers' => self::SUBSCRIBER_NONE,
    );
}

To register event listeners that you want to instantiate yourself in the cache kernel, overwrite getDefaultSubscribers:

use FOS\HttpCache\SymfonyCache\UserContextSubscriber;

// ...

public function getDefaultSubscribers()
{
    // get enabled listeners with default settings
    $subscribers = parent::getDefaultSubscribers();

    $subscribers[] = new UserContextListener(array(
        'session_name_prefix' => 'eZSESSID',
    ));

    $subscribers[] = new CustomListener();

    return $subscribers;
}

You can also register event listeners from outside the kernel, e.g. in your app.php with the addListener and addSubscriber methods.

Event Listeners¶

Each cache feature has its own event listener. The listeners are provided by the FOSHttpCache library. You can find the documentation for those listeners in the FOSHttpCache Symfony Cache documentation section.

@InvalidatePath¶

Invalidate a path:

use FOS\HttpCacheBundle\Configuration\InvalidatePath;

/**
 * @InvalidatePath("/articles")
 * @InvalidatePath("/articles/latest")
 */
public function editAction()
{
}

See Invalidation for more information.

@InvalidateRoute¶

Invalidate a route with parameters:

use FOS\HttpCacheBundle\Configuration\InvalidateRoute;

/**
 * @InvalidateRoute("articles")
 * @InvalidateRoute("articles", params={"type" = "latest"})
 */
public function editAction()
{
}

You can also use expressions in the route parameter values. This obviously requires the ExpressionLanguage component. To invalidate route articles with the number parameter set to 123, do:

/**
 * @InvalidateRoute("articles", params={"number" = {"expression"="id"}})
 */
public function editAction(Request $request, $id)
{
    // Assume $request->attributes->get('id') returns 123
}

The expression has access to all request attributes and the request itself under the name request.

See Invalidation for more information.

@Tag¶

You can make this bundle tag your response automatically using the @Tag annotation. Safe operations like GET that produce a successful response will lead to that response being tagged; modifying operations like POST, PUT, or DELETE will lead to the tags being invalidated.

When indexAction() returns a successful response for a safe (GET or HEAD) request, the response will get the tag news. The tag is set in a custom HTTP header (X-Cache-Tags, by default).

Any non-safe request to the editAction that returns a successful response will trigger invalidation of both the news and the news-123 tags.

Set/invalidate a tag:

/**
 * @Tag("news-article")
 */
public function showAction()
{
    // ...
}

GET /news/show will

Multiple tags are possible:

/**
 * @Tag("news")
 * @Tag("news-list")
 */
public function indexAction()
{
    // ...
}

If you prefer, you can combine tags in one annotation:

/**
 * @Tag({"news", "news-list"})
 */

You can also use expressions in tags. This obviously requires the ExpressionLanguage component. The following example sets the tag news-123 on the Response:

/**
 * @Tag(expression="'news-'~id")
 */
public function showAction($id)
{
    // Assume request parameter $id equals 123
}

Or, using a param converter:

/**
 * @Tag(expression="'news-'~article.getId()")
 */
public function showAction(Article $article)
{
    // Assume $article->getId() returns 123
}

See Tagging for an introduction to tagging. If you wish to change the HTTP header used for storing tags, see tags.

invalidatePath()¶

Invalidate a path:

$cacheManager->invalidatePath('/users')->flush();

Invalidate a URL:

$cacheManager->invalidatePath('http://www.example.com/users');

Invalidate a route:

$cacheManager = $container->get('fos_http_cache.cache_manager');
$cacheManager->invalidateRoute('user_details', array('id' => 123));

Invalidate a regular expression:

$cacheManager = $container->get('fos_http_cache.cache_manager');
$cacheManager->invalidateRegex('.*', 'image/png', array('example.com'));

The cache manager offers a fluent interface:

$cacheManager
    ->invalidateRoute('villains_index')
    ->invalidatePath('/bad/guys')
    ->invalidateRoute('villain_details', array('name' => 'Jaws')
    ->invalidateRoute('villain_details', array('name' => 'Goldfinger')
    ->invalidateRoute('villain_details', array('name' => 'Dr. No')
;

refreshPath() and refreshRoute()¶

Refresh a path:

$cacheManager = $container->get('fos_http_cache.cache_manager');
$cacheManager->refreshPath('/users');

Refresh a URL:

$cacheManager = $container->get('fos_http_cache.cache_manager');
$cacheManager->refreshPath('http://www.example.com/users');

Refresh a Route:

$cacheManager = $container->get('fos_http_cache.cache_manager');
$cacheManager->refreshRoute('user_details', array('id' => 123));

tagResponse(), invalidateTags()¶

flush()¶

Internally, the invalidation requests are queued and only sent out to your HTTP proxy when the manager is flushed. The manager is flushed automatically at the right moment:

• when handling a HTTP request, after the response has been sent to the client (Symfony’s kernel.terminate event)
• when running a console command, after the command has finished (Symfony’s console.terminate event).

You can also flush the cache manager manually:

$cacheManager->flush();

addTags()¶

Add tags to be sent with the response:

$tagHandler->addTags(array('some-tag', 'other-tag'));

This method can be called regardless of whether the response object already exists or not.

invalidateTags()¶

Invalidate cache tags:

$tagHandler->invalidateTags(array('some-tag', 'other-tag'));