Invalidate data cache whenever any entry or category is saved

[MoritzLost]

I'm building a controller that returns some data based on a lot of entries. I want to cache the output, but invalidate the cache whenever any entry included in the query is saved, another entry is added, or a category related to any of the entries is saved. I'm fine with invalidating caches whenever any entry or category is saved or added.

I've read the caching guide but I'm having a hard time figuring out how Craft uses cache tags. This is what I've got so far:

/** @var \yii\caching\CacheInterface $cache */
$cache = Craft::$app->getCache();

$cacheKey = [__CLASS__, __METHOD__, 'all-offers-data'];
if ($cachedResponse = $cache->get($cacheKey)) {
    return $this->asJson($cachedResponse);
}

$query = $this->getQuery();
$result = $this->process($query);

$dependency = new ElementQueryTagDependency($query);

$cache->set(
    $cacheKey,
    $result,
    self::CACHE_DURATION,
    $dependency,
);

This does invalidate the cache whenever any entry in the query is saved, but not when a related category or other element is saved.

I thought using more general cache tags would solve this, but I can't get it to work. I tried a couple different tags with TagDependency, but none of the following is working:

$dependency = new TagDependency(['tags' => [
    'element',
    'element::' . Category::class,
    'element::' . Entry::class,
]]);
$dependency = new TagDependency(['tags' => ['element']]);
$dependency = new TagDependency(['tags' => ['*']]);

Is there any way to create a cache dependency that will change whenever any entry or category is saved? And is there any documentation on how those cache tags in Craft work in detail?

[brandonkelly]

Here’s how you’d do it in Craft 3:

// Turn on element cache tag collection
Craft::$app->elements->startCollectingCacheTags();

// Execute the query
$query = $this->getQuery();
$result = $this->process($query);

// Stop collecting cache tag collection, and get the resulting TagDependency
$dependency = Craft::$app->elements->stopCollectingCacheTags();

// Cache the results with the dependency
$cache->set($cacheKey, $result, self::CACHE_DURATION, $dependency);

That will still work in Craft 4, but those two Elements service methods have been deprecated in favor of startCollectingCacheInfo() and stopCollectingCacheInfo(). The advantage of the new methods is that you will get the recommended cache duration back as well, which will be set based on the first-expiring entry in the results, if any.

// Turn on element cache info collection
Craft::$app->elements->startCollectingCacheInfo();

// Execute the query
$query = $this->getQuery();
$result = $this->process($query);

// Stop collecting cache tag collection, and get the resulting TagDependency
[$dependency, $duration] = Craft::$app->elements->stopCollectingCacheInfo();

// Cache the results with the dependency
$cache->set($cacheKey, $result, $duration ?? self::CACHE_DURATION, $dependency);

[MoritzLost]

@brandonkelly Thanks, that worked like a charm! Now the cache is cleared whenever any of the related categories are saved as well.

I still don't really understand those how those cache tags work though. The TagDependency returned by stopCollectionCacheInfo looks like this:

    0 => yii\caching\TagDependency#1
    (
        [data] => null
        [reusable] => false
        [tags] => [
            0 => 'element'
            1 => 'element::craft\\elements\\Entry'
            2 => 'element::craft\\elements\\Entry::section:8'
            3 => 'element::craft\\elements\\Entry::*'
            4 => 'element::craft\\elements\\Category'
            5 => 'element::craft\\elements\\Category::group:2'
            6 => 'element::verbb\\supertable\\elements\\SuperTableBlockElement'
            7 => 'element::verbb\\supertable\\elements\\SuperTableBlockElement::field:1'
        ]
    )

But how do those tags relate to each other? Supposedly, element::craft\\elements\\Entry should be invalidated whenever any Entry is saved? And element should be invalidated whenever any element is saved? In this case, why do I need the more specific tags as well? Apparently the more specific tags like element::craft\\elements\\Entry::section:8 are needed, but what is the relation between the less and more specific tags in this case?

Is there any guide regarding those cache tags beyond the caching guide in the Yii documentation? That one doesn't really go into detail regarding the correct usage of TagDependency …

[brandonkelly]

Each element query that is executed while cache tag collection is activated will define a list of tags for the resulting cache. Those tags are assigned to the TagDependency that is returned when tag collection ends. At a minimum, that list will include element and element::element\type\class, and then one or more tags that are more specific, depending on how detailed the element query wants to get based on its parameters.

In your case:

0 => 'element'

This would have been registered by each element query.

1 => 'element::craft\\elements\\Entry'

This would have been registered by each entry query.

2 => 'element::craft\\elements\\Entry::section:8'

This would have been registered by an entry query that specified a section or sectionId param, for a section where id=8.

3 => 'element::craft\\elements\\Entry::*'

This would have been registered by an entry query that didn’t specify an id, section, sectionId, type, or typeId param.

4 => 'element::craft\\elements\\Category'
5 => 'element::craft\\elements\\Category::group:2'

These would have been registered by a category query that specified a group or groupId param, for a category group where id=2.

6 => 'element::verbb\\supertable\\elements\\SuperTableBlockElement'
7 => 'element::verbb\\supertable\\elements\\Sup1rTableBlockElement::field:1'

These would have been registered by a Super Table block query that specified a field or fieldId param, for a Super Table field where id=1.

Supposedly, element::craft\\elements\\Entry should be invalidated whenever any Entry is saved? And element should be invalidated whenever any element is saved? In this case, why do I need the more specific tags as well? Apparently the more specific tags like element::craft\\elements\\Entry::section:8 are needed, but what is the relation between the less and more specific tags in this case?

element and element::craft\elements\Entry will only be invalidated when craft\services\Elements::invalidateAllCaches() and invalidateCachesForElementType() are called, respectively.

When an entry is saved, only caches with two sets of ::s will get invalidated.

• element::craft\elements\Entry::* for any entry queries that didn’t specify an id, section, sectionId, type, or typeId param.
• element::craft\elements\Entry::[EntryID] for any entry queries that specified an id param.
• element::craft\elements\Entry::drafts if the saved entry is a draft, for any draft-fetching entry queries.
• element::craft\elements\Entry::revisions if the saved entry is a revision, for any revision-fetching entry queries.
• element::craft\elements\Entry::section:[SectionID] for any entry queries that specified a section or sectionId param.
• element::craft\elements\Entry::entryType:[TypeID] for any entry queries that specified a type or typeId param.

Technically since this collection of tags includes at least one entry query that didn’t specify id, section, sectionId, type, and typeId, the ::section:8 tag could be omitted, as the cache is going to end up being invalidated each time any entry is saved via that ::* tag, but individual element queries aren’t aware of what tags other queries are registering, so there’s a tiny bit of extra effort going on here. It won’t make a difference performance-wise though, so not worth the effort to try and be smarter about it.

[MoritzLost]

@brandonkelly Awesome, thank you for the very thorough explanation! Now I get it, the missing piece for me was not knowing what tags get invalidated when a single entry is saved. Makes complete sense once you get it. So my original approach was not that far off, I was only missing the ::* to make sure the tags are invalidated when a single entry is saved. So this should work to invalidate my cache whenever any entry or category is saved:

$dependency = new TagDependency(['tags' => [
    'element',
    'element::' . Category::class . '::*',
    'element::' . Entry::class . '::*',
]]);

But of course, using the startCollectingCacheTags() method is much simpler and less error-prone!