XalokNext Documentation

Appearance

Varnish ​

v7.4+ XKey tags prefix ​

Intro ​

Since v7.4+, XalokNext supports prefixing the XKey tags with a certain value. This is helpful when different projects share the same Varnish server - each project can establish its own prefix, in order to avoid purging objects from a different project

This is also being used by multisite single-installation projects, each site is prefixing its responses and invalidation requests with sXX, where XX is the ID of the current site.

Enabling in single-site projects ​

In order to enable this feature, add a wf_cms.frontend_cache.tag_prefix parameter to your configuration.

Example: Prefixing all XKeys with a, both for responses and for invalidation requests

yaml
# In app/config/parameters/project.yml or app/config/parameters/local.yml
parameters:
  # ... other parameters ...
  wf_cms.frontend_cache.tag_prefix: 'a'

Example: Invalidate the a-assets XKey:

shell
./app/admin/console --env=prod wf:cms:frontend-cache:invalidate-tag assets

Enabling in multisite projects ​

For multisite projects the tags are automatically prefixed with sXX, where XX is the ID of the current site (the site that the editor is working on in the admin).

If one wants to purge tags from a different site, prefix them with sXX-, the tags processor will skip automatically prefixing these tags with the current site's ID. You need to do this if the code is dispatching the CLearTagsCacheMessage - prefix the tags with the current site's prefix at the time of dispatching this message. This is required because there is only one messenger consumer for all sites, it uses the defaultSite. So if one doesn't prefix this tag when dispatching, it'll always be invalidated for the defaultSite.

To help with this, one can use the TagsProcessorAwareTrait:

php
<?php

use Wf\Bundle\CmsBaseBundle\Frontend\Cache\TagsProcessorAwareTrait;

class X {
      use TagsProcessorAwareTrait;

      public function invalidateTag($tag) {
          $tag = $this->tagsProcessor->processTags($tag); // <-- do this to prefix the tag with the current site

          $this->messageBus->dispatch(new ClearTagsCacheMessage($tag));
      }
}

If not using autowire, one must call the setTagsProcessor method for that service:

xml
<service id="x" class="X">
      <call method="setTagsProcessor">
          <argument type="service" id="wf_cms.frontend_cache.tags_processor" />
      </call>
</service>

The ClearTagsCacheMessage was changed to accept a second argument $global, by default false. This is set to true where needed, e.g. when purging a user's tag (one user can publish in multiple sites) or for global settings

Troubleshooting ​

The prefix is added to the response tags added by wf_cms.handler.tag_handler and also in the invalidations issued by wf_cms.frontend_cache.manager.

That is to say: check whether your project is using either of these services:

  • fos_http_cache.http.symfony_response_tagger
  • FOS\HttpCacheBundle\Http\SymfonyResponseTagger
  • fos_http_cache.cache_manager
  • FOS\HttpCacheBundle\CacheManager

Use wf_cms.handler.tag_handler and wf_cms.frontend_cache.manager instead.

Also: fos:httpcache:invalidate:tag assets leaves the tag as it is, use wf:cms:frontend-cache:invalidate-tag if you want to prefix it.

Clearing Varnish ​

Using varnishadm ​

To purge the cache on the frontend server run:

shell
/usr/bin/varnishadm -S /etc/varnish/secret -T 127.0.0.1:6082 ban "req.url ~ .*"

Varnish matches the cached objects' URLs against the regular expression .*.

⚠️ The Varnish cache should NEVER be cleared entirely (.*) when running in production as that would mean that all the requests must be served by the middles, increasing the load. Instead, in case this is required, purge the cache selectively, only a few URLs at a time.

To purge Varnish cache more selectively:

  • For the category economia:
shell
/usr/bin/varnishadm -S /etc/varnish/secret -T 127.0.0.1:6082 ban "req.url ~ /economia"
  • For all category economia and all its subcategories + articles in economia category:
shell
/usr/bin/varnishadm -S /etc/varnish/secret -T 127.0.0.1:6082 ban "req.url ~ /economia/.*"
  • For purging individual boards: each of the boards has a slug (the developer knows the slugs of boards). The boards are served by the URL: /page/_BOARD_SLUG.html . So the request to purge the cache for a specific board is:
shell
/usr/bin/varnishadm -S /etc/varnish/secret -T 127.0.0.1:6082 ban "req.url ~ /page/__BOARD_SLUG__.html"

Invalidate (purge) tag command for all categories ​

shell
./app/admin/console --env=prod wf:cms:frontend-cache:invalidate-categories

Invalidate (purge) tag command in single-site projects ​

shell
./app/admin/console --env=prod wf:cms:frontend-cache:invalidate-tag -f assets

You can invalidate multiple tags at once, by separating them with a comma (,):

shell
./app/admin/console --env=prod wf:cms:frontend-cache:invalidate-tag -f assets,assets-css,assets-js

v7.4+ Invalidate (purge) tag command in multisite projects ​

The commands above will invalidate the tags for the configured defaultSite.

To invalidate the tags for a different site:

shell
SITE=another_site_short_name ./app/admin/console --env=prod wf:cms:frontend-cache:invalidate-tag -f assets,assets-css,assets-js

To invalidate the tags for all the sites:

shell
./app/admin/console --env=prod --all-sites wf:cms:frontend-cache:invalidate-tag -f assets,assets-css,assets-js