README

基于URL而不是数据库查询的模板缓存。

功能

• 缓存键是从请求对象中可用的信息构建的（意味着无需数据库调用）
• 当DataObject被修改时的无效化钩子
• 使用 doctrine/cache 库，提供许多缓存后端
• 使用Symfony表达式语言进行精细的无效化控制
• 支持模板中的 <% cache_include 'TemplateName' %> 语法
• 支持模板中的 <% cache %><% end_cache %> 语法
• 包含替换安全令牌能力的完整请求缓存
• 高度可定制
• 当缓存命中时设置请求头，以简化测试，例如在Thu, 03 Mar 2022 14:23:41 -0600时命中

安装

$ composer require heyday/silverstripe-cacheinclude:~5.0

如何使用

启用

要能够在DataObject写入时使缓存无效，请添加 InvalidationExtension

1. 创建配置文件 mysite/_config/caching.yml
2. 将以下内容添加到yml文件中

---
After: 'silverstripe-cacheinclude/*'
---
SilverStripe\ORM\DataObject:
  extensions:
    - Heyday\CacheInclude\SilverStripe\InvalidationExtension

模板使用

缓存模板的一部分

<% cache 'SomeCacheBlock' %>
<% loop ExpensiveSet %><% end_loop %>
<% end_cache %>

缓存一个包含的模板（假设缓存块配置名为 SomeTemplateName）

<% cache_include 'SomeTemplateName' %>

使用不同的缓存块配置名称缓存一个包含的模板

<% cache_include 'App\Includes\SomeTemplateName', 'CacheBlockConfigName' %>

缓存块配置

对于每个使用的缓存块，您需要提供给 CacheInclude 的相应配置。

以下是一个针对 SomeCacheBlock 和 AnotherCacheBlock 的配置示例

mysite/_config/caching.yml

---
After: 'silverstripe-cacheinclude/*'
---
Injector:
  CacheIncludeConfig:
    class: Heyday\CacheInclude\Configs\ArrayConfig
    properties:
      Config:
        SomeCacheBlock:
          context: full
          contains:
            - MyDataObject
        AnotherCacheBlock:
          context: no
          expires: +1 hour

配置选项

键创建选项

上下文

上下文是一种方法，告诉键创建器在创建键时包含请求的哪些信息。

可能的值

• no
  • 创建的键与请求无关
• host
  • 使用主机名创建键，当使用子站或多个基础域名时很有用
• page
  • 基于URL创建键，但不包括GET变量
• full
  • 基于URL创建键，包括GET变量

expires

可能的值

• (string)
  • 传递给strtotime的字符串，例如 '+1 hour'
• (int)
  • 秒数

member

可能的值

• true
  • 将为每个登录成员创建一个新的缓存
• any
  • 将创建一个组（当没有登录的人时，另一个键）的新缓存成员

versions

可能的值

• (int)
  • 将此设置为整数，以创建指定数量的缓存版本

这对于当缓存块包含随机内容时很有用，但您仍然想要缓存。

例如，设置为20以获得20（可能）不同的缓存块版本。

缓存无效化选项

contains

• (array)
  • 一个类名数组，如果保存的记录与缓存匹配，则缓存将无效

invalidation_rules

• (array)
  • 一个由可用的表达式语言编写的规则数组。如果匹配规则，则缓存将无效

表达式语言由Symfony提供，但也提供了以下内容

变量

• item
• action

函数

• list()
• instanceof()

这些可以用于以下操作

  invalidation_rules:
    - "instanceof(item, 'CreativeProfile') and item.ID in list('CreativeProfile').sort('Created DESC').limit(4).getIDList()"

完整请求缓存

CacheInclude自带一个RequestCache服务，可以将完整请求对象添加到缓存中，以在高负载网站上使用。

启用

要启用完整的请求缓存，需要应用RequestCacheMiddleware并创建一个Global配置块。

---
After: '#cacheinclude'
---
SilverStripe\Core\Injector\Injector:
  CacheIncludeConfig:
    class: Heyday\CacheInclude\Configs\ArrayConfig
    properties:
      Config:
        Global:
          contains:
            - SilverStripe\CMS\Model\SiteTree
          context: full
          expires: '+ 1 hour'
---
After: '#coresecurity'
---
SilverStripe\Core\Injector\Injector:
  SilverStripe\Control\Director:
    properties:
      Middlewares:
        RequestCacheMiddleware: '%$RequestCacheMiddleware'

注意：上述示例中的After:条件非常重要。没有它，处理请求缓存的中间件将在SilverStripe的认证中间件之前运行——这意味着当前用户（存储在会话中）不可用。这可能导致用户之间的缓存污染，或者访客与注册用户之间的缓存污染。

完整的请求缓存可以显著提高性能，但它并非没有代价。由于其配置复杂，存在许多你不想缓存请求或服务缓存请求的情况。

为了帮助解决这个问题，你可以直接配置缓存处理方式。

以下给出了一些配置示例和你可以做的事情。

Injector:
  RequestCacheMiddleware:
    class: 'Heyday\CacheInclude\SilverStripe\RequestCacheMiddleware'
    constructor:
      0: '%$CacheInclude'
      1: '%$CacheIncludeExpressionLanguage'
      2: 'Global'
    properties:
      Tokens:
        - '%$SilverStripe\Security\SecurityToken'
      SaveExcludeRules:
        - 'request.getUrl() matches "{^admin|dev}"'
      SaveIncludeRules:
        - "request.httpMethod() == 'GET'"
        - 'response.getStatusCode() == 200'
      FetchExcludeRules:
        - 'request.getUrl() matches "{^admin|dev}"'
      FetchIncludeRules:
        - "request.httpMethod() == 'GET'"

如你所见，表达式语言中提供了一些可访问的变量。

以下是在“保存”规则中可用的内容：

• 请求
• 响应
• member
• 会话

以下是在“获取”规则中可用的内容：

• 请求
• member
• 会话

可以通过注入系统提供额外的变量。

Injector:
  RequestCacheMiddleware:
    properties:
      ExtraExpressionVars:
        'hello': 'Something'

自定义

由于大量使用依赖注入和SilverStripe的Injector组件，大多数CacheInclude部分都可以通过替换标准类为你的自定义类进行完全自定义。

密钥创建者

CacheInclude内置了一个密钥创建者Heyday\CacheInclude\KeyCreators\ControllerBased。这个密钥创建者基于在yaml中提供的配置、当前请求和环境来创建密钥。

你可以通过扩展KeyCreatorInterface并指定从模板中指定的创建者的服务名称来创建自己的密钥创建者。

<% cache 'SomeBlock', 'MyKeyCreator' %>
Some content
<% end_cache %>

class MyKeyCreator implements \Heyday\CacheInclude\KeyCreators\KeyCreatorInterface
{
    public function getKey($name, $config)
    {
        return [
           'key',
           'parts'
        ];
    }
}

许可

SilverStripe CacheInclude在MIT许可下发布。

贡献

单元测试

$ composer install --prefer-dist --dev
$ phpunit

代码规范

此项目遵循以下定义的标准：

• PSR-0
• PSR-1
• PSR-2

在贡献之前，请运行以下命令：

$ php-cs-fixer fix .