PHPackages                             mmikkel/cache-flag - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. mmikkel/cache-flag

ActiveCraft-plugin[Caching](/categories/caching)

mmikkel/cache-flag
==================

Cold template caches that can be flagged and automatically invalidated.

2.0.3(1mo ago)1730.4k↑13.3%1MITPHPPHP ^8.2

Since Jul 16Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/mmikkel/CacheFlag-Craft3)[ Packagist](https://packagist.org/packages/mmikkel/cache-flag)[ RSS](/packages/mmikkel-cache-flag/feed)WikiDiscussions master Synced yesterday

READMEChangelog (10)Dependencies (2)Versions (29)Used By (1)

Cache Flag plugin for Craft CMS
===============================

[](#cache-flag-plugin-for-craft-cms)

[![Scrutinizer Code Quality](https://camo.githubusercontent.com/62beefee5dda87e498327a93dc90d8e3160cb61acbd1779ef6ce49bd8b7d9c5a/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6d6d696b6b656c2f4361636865466c61672d4372616674332f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/mmikkel/CacheFlag-Craft3/?branch=master)

Cache Flag is a Craft CMS plugin that adds an alternative cache invalidation strategy to template caches, using manually defined keywords ("flags").

Why does this plugin exist?
---------------------------

[](#why-does-this-plugin-exist)

Cache Flag was originally designed to circumvent common performance issues with the native `{% cache %}` tag's element query based invalidation strategy.

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!**

However, Cache Flag is still a valid alternative to the native `{% cache %}` tag if you want to

- Implement automatic or manual bulk template cache invalidation (optionally, in combination with Craft's native element-based cache invalidation)
- Cache arbitrary HTML output and implement your own invalidation strategies for it
- Have completely cold template caches (like the [Cold Cache plugin](https://github.com/pixelandtonic/ColdCache), which is not available for Craft 5)

Table of contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Using Cache Flag](#using-cache-flag)
- [Dynamic flags](#dynamic-flags)
- [Arbitrary flags](#arbitrary-flags)
- [Collecting element tags for automatic cache invalidation](#collecting-element-tags-for-automatic-cache-invalidation)
- [Cold caches](#cold-caches)
- [Invalidating flagged caches](#invalidating-flagged-caches)
- [Additional parameters](#additional-parameters)
- [Project Config](#project-config)
- [Events](#events)

Requirements
------------

[](#requirements)

**This plugin requires Craft CMS 5.0+**

Using Cache Flag
----------------

[](#using-cache-flag)

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*).

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.

*Here's how it looks in action:*

```
{% cacheflag flagged "news|images" %}
    {% set entries = craft.entries.section('news').all() %}
    ...
{% endcacheflag %}
```

**Note that multiple flags are separated using the pipe delimiter (`|`).**

**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`](#collecting-element-tags-for-automatic-cache-invalidation) directive.

### I'm going to need an example.

[](#im-going-to-need-an-example)

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:

[![The Cache Flag CP utility](resources/utility.png)](resources/utility.png)

Then, you add that same `news` flag to any relevant caches, using the `{% cacheflag %}` tag and the `flagged` parameter:

```
{% 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.

Dynamic flags
-------------

[](#dynamic-flags)

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:

```
{% cacheflag flagged "entry:#{entry.id}" %}
    ...
{% endcacheflag %}
```

or if you prefer:

```
{% cacheflag flagged "entry:#{entry.uid}" %}
    ...
{% endcacheflag %}
```

All native element types can be used in dynamic flags:

`entry:#{entry.id}`
`asset:#{asset.id}`
`category:#{category.id}`
`tag:#{tag.id}`
`globalSet:#{globalSet.id}`
`user:#{user.id}`

It's also possible to use the `element` prefix, which works for all element types (including custom/third party ones):

`element:#{element.id}`
`element:#{element.uid}`

Of course, it's possible to combine both standard and dynamic cache flags for a single cache:

```
{% cacheflag flagged "news|employees|entry:#{entry.id}|category:#{category.id}" %}
    ...
{% endcacheflag %}
```

Arbitrary flags
---------------

[](#arbitrary-flags)

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).

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:

```
{% 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](#invalidating-flagged-caches).

Collecting element tags for automatic cache invalidation
--------------------------------------------------------

[](#collecting-element-tags-for-automatic-cache-invalidation)

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.

If you want Cache Flag to collect element tags for automatic cache invalidation, you can add the `with elements` directive like this:

```
{% 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.

Cold caches
-----------

[](#cold-caches)

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](#invalidating-flagged-caches)*):

```
{% cacheflag for 360 days %}
    ...
{% endcacheflag %}
```

**Tip:** If you're upgrading a Craft 2 site that uses the [Cold Cache plugin](https://straightupcraft.com/craft-plugins/cold-cache), this is one way to achive the same thing on Craft 3.

Invalidating flagged caches
---------------------------

[](#invalidating-flagged-caches)

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](#dynamic-flags). These caches are invalidated whenever relevant elements are saved, deleted, moved or changes status.

Cold caches and caches using [arbitrary flags](#arbitrary-flags) must be invalidated manually or programmatically (see below).

### Manual cache invalidation

[](#manual-cache-invalidation)

Flagged template caches can be manually invalidated by

- Using the native Clear Caches utility in the Craft CP (check out the [CP Clear Cache plugin](https://plugins.craftcms.com/cp-clearcache) for easier access to this tool)
- Clicking the "Invalidate all flagged caches" button in Cache Flag's CP utility
- Using the native CLI command `invalidate-tags/cacheflag`
- Using the native CLI command `invalidate-tags/template` (invalidates all template caches, including flagged ones)
- Using the native CLI command `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](#arbitrary-flags)):

```
./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.

Finally, flushing the data cache will *delete* all template caches, including flagged ones.

### Programmatic cache invalidation

[](#programmatic-cache-invalidation)

```
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']);
```

Additional parameters
---------------------

[](#additional-parameters)

Beyond the `flagged` and `with elements` parameters, the `{% cacheflag %}` tag *supports all the same parameters* as \[the native `{% cache %}` tag\[()\].

Project Config and `allowAdminChanges`
--------------------------------------

[](#project-config-and-allowadminchanges)

Cache Flag supports [Project Config](https://docs.craftcms.com/v3/project-config.html) 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.**

Events
------

[](#events)

Cache Flag dispatches two events:

- `beforeInvalidateFlaggedCaches`
    *Dispatched just before Cache Flag invalidates one or several flagged template caches.*
- `afterInvalidateFlaggedCaches`
    *Dispatched immediately after Cache Flag has invalidated one or several flagged template caches.*

Both events include a parameter `flags`, which is an array of the flags Cache Flag is invalidating caches for.

### Listening to Cache Flag events

[](#listening-to-cache-flag-events)

```
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.

###  Health Score

60

—

FairBetter than 98% of packages

Maintenance88

Actively maintained with recent releases

Popularity34

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity86

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~114 days

Recently: every ~108 days

Total

26

Last Release

59d ago

Major Versions

1.4.0 → 2.0.0-beta.12024-02-15

1.4.1 → 2.0.12025-02-27

v1.x-dev → 2.0.22025-06-16

PHP version history (2 changes)1.3.0PHP ^7.2.5|^8.0

2.0.0-beta.1PHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/298510?v=4)[M. Mikkel Rummelhoff](/maintainers/mmikkel)[@mmikkel](https://github.com/mmikkel)

---

Top Contributors

[![mmikkel](https://avatars.githubusercontent.com/u/298510?v=4)](https://github.com/mmikkel "mmikkel (61 commits)")

---

Tags

cmsCraftcraftcmscraft-plugincache flag

### Embed Badge

![Health badge](/badges/mmikkel-cache-flag/health.svg)

```
[![Health](https://phpackages.com/badges/mmikkel-cache-flag/health.svg)](https://phpackages.com/packages/mmikkel-cache-flag)
```

###  Alternatives

[verbb/formie

The most user-friendly forms plugin for Craft.

102393.6k69](/packages/verbb-formie)[verbb/vizy

A flexible visual editor field for Craft.

4250.4k](/packages/verbb-vizy)[verbb/hyper

A user-friendly links field for Craft.

24147.8k12](/packages/verbb-hyper)[verbb/social-poster

Automatically post entries to social media.

918.5k](/packages/verbb-social-poster)[verbb/events

A full-featured plugin for event management and ticketing.

2311.9k](/packages/verbb-events)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)