Wallogit.com
2017 © Pedro Peláez
Cold template caches that can be flagged and automatically cleared.
, (*1)
Cache Flag is a Craft CMS plugin that adds an alternative cache invalidation strategy to template caches, using manually defined keywords ("flags")., (*2)
Cache Flag was originally designed to circumvent common performance issues with the native {% cache %} tag's element query based invalidation strategy., (*3)
Since Craft 3.5.0, said performance issues have been solved in core, making Cache Flag redundant for its primary use case. If you were previously using Cache Flag only to avoid performance issues with {% cache %}, you probably don't need it anymore!, (*4)
However, Cache Flag is still a valid alternative to the native {% cache %} tag if you want to, (*5)
This plugin requires Craft CMS 5.0+, (*6)
Cache Flag adds a new {% cacheflag %} Twig tag to Craft CMS, which works just like the native {% cache %} tag - except that by default, Cache Flag's template caches are "cold" (i.e. Cache Flag will not save element queries for automatic cache invalidation)., (*7)
For cache invalidation, Cache Flag adds the ability to "flag" template caches and content with keywords ("flags"). Whenever an element is saved, moved or deleted, Cache Flag will automatically invalidate any flagged template caches matching that element's flags., (*8)
Here's how it looks in action:, (*9)
{% cacheflag flagged "news|images" %}
{% set entries = craft.entries.section('news').all() %}
...
{% endcacheflag %}
Note that multiple flags are separated using the pipe delimiter (|)., (*10)
Tip: In addition to the flagged parameter it's also possible to have Cache Flag clear caches automatically in the same way the native {% cache %} tag does, using the new with elements directive., (*11)
Sure. Let's assume you have a section called "News", and there's a cache that you want to invalidate whenever the content in that section changes (i.e. if entries are saved, deleted, changes status etc). First, you add the flag news (or whatever, the flags can be anything, really) to the "News" section in Cache Flag's CP utility:, (*12)
, (*13)
Then, you add that same news flag to any relevant caches, using the {% cacheflag %} tag and the flagged parameter:, (*14)
{% cacheflag flagged "news" %}
{% set entries = craft.entries... %}
...
{% endcacheflag %}
Now, whenever an entry in the "News" section is saved, moved, deleted or changes status, any caches flagged with news will be automatically invalidated., (*15)
It's possible to flag caches using dynamic flags based on element IDs and/or UIDs. If you wanted to ensure that a cache is invalidated whenever a particular element is edited, moved or deleted, you can do this:, (*16)
{% cacheflag flagged "entry:#{entry.id}" %}
...
{% endcacheflag %}
or if you prefer:, (*17)
{% cacheflag flagged "entry:#{entry.uid}" %}
...
{% endcacheflag %}
All native element types can be used in dynamic flags:, (*18)
entry:#{entry.id}
asset:#{asset.id}
category:#{category.id}
tag:#{tag.id}
globalSet:#{globalSet.id}
user:#{user.id}, (*19)
It's also possible to use the element prefix, which works for all element types (including custom/third party ones):, (*20)
element:#{element.id}
element:#{element.uid}, (*21)
Of course, it's possible to combine both standard and dynamic cache flags for a single cache:, (*22)
{% cacheflag flagged "news|employees|entry:#{entry.id}|category:#{category.id}" %}
...
{% endcacheflag %}
The flags you add to your {% cachetags %} caches can be literally anything - and they don't have to be added to an element source (or be dynamic)., (*23)
A good use case for arbitrary flags is when you've got a cache that don't involve any elements, for example if you wanted to cache output dependent on an external API call or something else that is time-consuming to parse on every request, e.g. something like this:, (*24)
{% cacheflag flagged "somearbitraryflag" %}
{% set data = craft.somePlugin.doExpensiveApiCall() %}
...
{% endcacheflag %}
If you use arbitrary flags, keep in mind that there's nothing that will actually invalidate those caches automatically (they'll essentially be cold caches, albeit flagged). Read up on the different options available for invalidating these - and other - flagged caches here., (*25)
Since Cache Flag 1.1.0 (Craft 3.5.0-RC1 or later), it's possible to collect element tags (in addition to your own flags) for automatic cache invalidation just like the native {% cache %} tag does., (*26)
If you want Cache Flag to collect element tags for automatic cache invalidation, you can add the with elements directive like this:, (*27)
{% cacheflag flagged "awesome" with elements %}
...
{% endcacheflag %}
Note: It's also possible to omit the flagged parameter and only use with elements, but at that point the {% cacheflag %} tag would work identically to the native {% cache %} tag, and you should probably just use the latter., (*28)
If both flagged and with elements are omitted from a {% cacheflag %} tag, that cache will be completely "cold", and it will only be invalidated if/when it expires, or if a user manually invalidates it (or clears the entire data cache) via the Control Panel or the Craft CLI (see also invalidating flagged caches):, (*29)
{% cacheflag for 360 days %}
...
{% endcacheflag %}
Tip: If you're upgrading a Craft 2 site that uses the Cold Cache plugin, this is one way to achive the same thing on Craft 3., (*30)
Cache Flag will automatically invalidate any caches with flags saved to one or multiple element sources defined in Cache Flag's CP utility, and caches using dynamic flags. These caches are invalidated whenever relevant elements are saved, deleted, moved or changes status., (*31)
Cold caches and caches using arbitrary flags must be invalidated manually or programmatically (see below)., (*32)
Flagged template caches can be manually invalidated by, (*33)
invalidate-tags/cacheflag invalidate-tags/template (invalidates all template caches, including flagged ones) invalidate-tags/all (invalidates all caches, including template caches) Additionally, Cache Flag exposes its own cache-flag/caches/invalidate CLI command, that can be used if you want to clear flagged template caches for specific flags (this also works with arbitrary flags):, (*34)
./craft cache-flag/caches/invalidate news,images,awesome
If you want to clear flagged caches over HTTP there's also a web controller action cache-flag/caches/invalidate which can be hit with a GET or POST request. This controller action will invalidate all flagged template caches, unless a parameter flags (string[]; array of flags) is present in the request., (*35)
Finally, flushing the data cache will delete all template caches, including flagged ones., (*36)
use mmikkel\cacheflag\CacheFlag; // Invalidate all flagged caches CacheFlag::getInstance()->cacheFlag->invalidateAllFlaggedCaches(); // Invalidate caches for a particular element CacheFlag::getInstance()->cacheFlag->invalidateFlaggedCachesByElement($entry); // Invalidate caches for one or several flags CacheFlag::getInstance()->cacheFlag->invalidateFlaggedCachesByFlags(['news', 'images']);
Beyond the flagged and with elements parameters, the {% cacheflag %} tag supports all the same parameters as [the native {% cache %} tag[(https://docs.craftcms.com/v3/dev/tags/cache.html#app)]., (*37)
allowAdminChanges
Cache Flag supports Project Config since v. 1.2.0 (Craft 3.5.0 or later only). If you're upgrading from an earlier version of Cache Flag, the relevant .yaml files will be automatically created after upgrading and running migrations., (*38)
Cache Flag dispatches two events:, (*39)
beforeInvalidateFlaggedCaches
Dispatched just before Cache Flag invalidates one or several flagged template caches., (*40)
afterInvalidateFlaggedCaches
Dispatched immediately after Cache Flag has invalidated one or several flagged template caches., (*41)
Both events include a parameter flags, which is an array of the flags Cache Flag is invalidating caches for., (*42)
use mmikkel\cacheflag\events\FlaggedTemplateCachesEvent;
use mmikkel\cacheflag\services\CacheFlagService;
use yii\base\Event;
Event::on(
CacheFlagService::class,
CacheFlagService::EVENT_BEFORE_INVALIDATE_FLAGGED_CACHES,
function (FlaggedTemplateCachesEvent $event) {
$flags = $event->flags;
...
}
);
Event::on(
CacheFlagService::class,
CacheFlagService::EVENT_AFTER_INVALIDATE_FLAGGED_CACHES,
function (FlaggedTemplateCachesEvent $event) {
$flags = $event->flags;
...
}
);
Note: Before Cache Flag 1.1.0, the EVENT_AFTER_DELETE_FLAGGED_CACHES (now deprecated in favor of EVENT_AFTER_INVALIDATE_FLAGGED_CACHES) would only be dispatched if caches were actually deleted. In Cache Flag 1.1.0+, the EVENT_AFTER_INVALIDATE_FLAGGED_CACHES event is dispatched regardless of whether any caches were actually cleared., (*43)
Cold template caches that can be flagged and automatically cleared.
MIT
cms craftcms craft-plugin craft cache flag
Cold template caches that can be flagged and automatically cleared.
MIT
cms craftcms craft-plugin craft cache flag
Cold template caches that can be flagged and automatically cleared.
MIT
cms craftcms craft-plugin craft cache flag