README

Cache Flag是一个Craft CMS插件，它为模板缓存添加了一种替代的缓存失效策略，使用手动定义的关键字（“标志”）。

为什么这个插件存在？

Cache Flag最初是为了绕过原生{% cache %}标签的基于元素查询的失效策略的常见性能问题而设计的。

自从Craft 3.5.0以来，这些性能问题已在核心中解决，使得Cache Flag对于其主要用途变得冗余。如果您之前仅使用Cache Flag来避免{% cache %}的性能问题，那么您可能不再需要它了！

然而，如果您想

• 实现自动或手动批量模板缓存失效（可选地，与Craft的本地基于元素的缓存失效结合使用）
• 缓存任意HTML输出并为它实现自己的失效策略
• 拥有完全的冷模板缓存（如Cold Cache插件，该插件对Craft 5不可用）

目录

• 要求
• 使用Cache Flag
• 动态标志
• 任意标志
• 收集元素标签以实现自动缓存失效
• 冷缓存
• 失效已标记的缓存
• 其他参数
• 项目配置
• 事件

要求

此插件需要Craft CMS 5.0+

使用Cache Flag

Cache Flag为Craft CMS添加了一个新的{% cacheflag %}Twig标签，它的工作方式与原生{% cache %}标签相同 - 不同之处在于，Cache Flag的模板缓存默认是“冷”的（即Cache Flag不会保存元素查询以实现自动缓存失效）。

对于缓存失效，Cache Flag添加了使用关键字（“标志”）标记模板缓存和内容的能力。每当一个元素被保存、移动或删除时，Cache Flag将自动失效任何匹配该元素标志的已标记模板缓存。

以下是实际操作中的样子

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

注意，多个标志使用竖线分隔符（|）。

提示：除了flagged参数之外，还可以使用Cache Flag以与原生{% cache %}标签相同的方式自动清除缓存，使用新的with elements指令。

我需要举个例子。

当然。假设你有一个名为“新闻”的部分，并且你想在更改该部分内容时使缓存失效（即，如果条目被保存、删除、更改状态等）。首先，你在Cache Flag的CP实用程序中将标志news（或任何其他，标志可以是任何东西）添加到“新闻”部分

然后，你使用{% cacheflag %}标签和flagged参数将相同的news标志添加到任何相关的缓存中

{% cacheflag flagged "news" %}
    {% set entries = craft.entries... %}
    ...
{% endcacheflag %}

现在，每当“新闻”部分的条目被保存、移动、删除或更改状态时，任何标记为news的缓存将自动失效。

动态标志

可以使用基于元素ID和/或UID的动态标志来标记缓存。如果您想确保在编辑、移动或删除特定元素时使缓存失效，您可以这样做

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

或者如果您更喜欢

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

所有本地元素类型都可以用于动态标志

entry:#{entry.id}
asset:#{asset.id}
category:#{category.id}
tag:#{tag.id}
全局设置：#{globalSet.id}
用户：#{user.id}

还可以使用element前缀，它适用于所有元素类型（包括自定义/第三方元素）

元素：#{element.id}
元素：#{element.uid}

当然，可以为单个缓存同时使用标准和动态缓存标志

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

任意标志

添加到您的{% cachetags %}缓存中的标志可以是任何内容，并且不需要添加到元素源（或动态）。

任意标志的一个好用法是，当您有一个不涉及任何元素的缓存时，例如，如果您想缓存依赖于外部API调用或每次请求都要解析的耗时操作的结果，例如以下内容

{% cacheflag flagged "somearbitraryflag" %}
    {% set data = craft.somePlugin.doExpensiveApiCall() %}
    ...
{% endcacheflag %}

如果您使用任意标志，请注意，没有任何机制会自动使这些缓存失效（它们基本上是冷缓存，尽管有标志）。请参阅此处可用的不同选项，用于使这些以及其他标记缓存失效。

收集元素标签以实现自动缓存失效

自Cache Flag 1.1.0（Craft 3.5.0-RC1或更高版本）以来，可以收集元素标签（除了您自己的标志）以进行自动缓存失效，就像原生的{% cache %}标签一样。

如果您想让Cache Flag收集元素标签以进行自动缓存失效，可以添加如下所示的with elements指令

{% cacheflag flagged "awesome" with elements %}
    ...
{% endcacheflag %}

注意：也可以省略flagged参数，只使用with elements，但在此情况下，{% cacheflag %}标签将与原生{% cache %}标签的工作方式完全相同，您可能只需使用后者。

冷缓存

如果从{% cacheflag %}标签中省略了flagged和with elements，那么该缓存将完全“冷”缓存，并且只有在它过期或用户通过控制面板或Craft CLI手动使其失效（或清除整个数据缓存）时才会失效。

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

提示：如果您正在升级一个使用Cold Cache插件的Craft 2站点，这是在Craft 3上实现相同功能的一种方法。

失效已标记的缓存

Cache Flag会自动使所有保存到Cache Flag CP实用程序中定义的一个或多个元素源中的标志的缓存失效，以及使用动态标志的缓存。当相关元素被保存、删除、移动或更改状态时，这些缓存将失效。

冷缓存和使用任意标志的缓存必须手动或通过程序使失效（见下文）。

手动缓存失效

可以通过以下方式手动使标记模板缓存失效：

• 使用Craft CP中的原生清除缓存实用程序（检查CP Clear Cache插件以更轻松地访问此工具）
• 在Cache Flag的CP实用程序中点击“使所有标记缓存失效”按钮
• 使用原生的CLI命令invalidate-tags/cacheflag
• 使用原生的CLI命令invalidate-tags/template（使所有模板缓存失效，包括标记缓存）
• 使用原生的CLI命令invalidate-tags/all（使所有缓存失效，包括模板缓存）

此外，Cache Flag还公开了其自己的cache-flag/caches/invalidate CLI命令，可用于清除具有特定标志的标记模板缓存（这也适用于任意标志）

./craft cache-flag/caches/invalidate news,images,awesome

如果您想通过HTTP清除标记缓存，还有一个可以接受GET或POST请求的web控制器操作cache-flag/caches/invalidate。此控制器操作将使所有标记模板缓存失效，除非请求中存在参数flags（string[]；标志数组）。

最后，清除数据缓存将删除所有模板缓存，包括标记的缓存。

程序化缓存失效

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

其他参数

除了标记和带有元素参数之外，{% cacheflag %}标签支持与原生{% cache %}标签相同的所有参数。[详见原生{% cache %}标签文档)

项目配置和allowAdminChanges

Cache Flag从v. 1.2.0开始支持项目配置（仅限Craft 3.5.0或更高版本）。如果您是从Cache Flag的早期版本升级的，升级并运行迁移后，将自动创建相关的.yaml文件。

事件

Cache Flag触发两个事件

• beforeInvalidateFlaggedCaches
  在Cache Flag清除一个或多个标记的模板缓存之前触发。

• afterInvalidateFlaggedCaches
  在Cache Flag清除一个或多个标记的模板缓存后立即触发。

这两个事件都包含一个名为flags的参数，它是一个数组，表示Cache Flag将对其缓存进行失效的标记。

监听Cache Flag事件

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

注意：在Cache Flag 1.1.0之前，EVENT_AFTER_DELETE_FLAGGED_CACHES（现在已被EVENT_AFTER_INVALIDATE_FLAGGED_CACHES替代）仅在缓存实际上被删除时才会触发。在Cache Flag 1.1.0+中，EVENT_AFTER_INVALIDATE_FLAGGED_CACHES事件无论是否实际清除了任何缓存都会触发。