Annotations

Annotate your controller actions to invalidate routes and paths when those actions are executed.

Note

Annotations need the SensioFrameworkExtraBundle including registering the Doctrine AnnotationsRegistry. Some features also need the ExpressionLanguage. Make sure to install the dependencies first.

@InvalidatePath

Invalidate a path:

use FOS\HttpCacheBundle\Configuration\InvalidatePath;

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

From PHP 8, you can replace the doctrine annotations by PHP attributes:

use FOS\HttpCacheBundle\Configuration\InvalidatePath;

#[InvalidatePath('/articles')]
#[InvalidatePath('/articles/latest')]
public function editAction()
{
}

When editAction() returns a successful response to an unsafe HTTP request (POST, PUT, PATCH or DELETE), the paths /articles and /articles/latest will be invalidated.

See Invalidation for more information.

@InvalidateRoute

Like InvalidatePath annotations, you can use PHP attributes instead if you are using PHP 8 Invalidate a route with parameters:

use FOS\HttpCacheBundle\Configuration\InvalidateRoute;

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

Similarly to @InvalidatePath above, any successful response to an unsafe request will invalidate the two routes.

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.

Like InvalidatePath annotations, you can use PHP attributes instead if you are using PHP 8

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.