README

TYPO3扩展 cache_bags

📦 Packagist | 🐥 TYPO3扩展仓库 | 💾 仓库 | 🐛 问题跟踪

一个为TYPO3 CMS构建和注册缓存包的扩展，以增强缓存控制。缓存包在运行时构建在未缓存的页面上，可以用来定义缓存元数据，如缓存标签。此外，它们用于计算特定缓存条目的过期日期。这允许根据内容和它们的显式依赖（如特定数据库内容或短暂的API请求）进行精细的缓存控制。

🚀 特点

• 支持不同缓存作用域（例如页面）的缓存包界面
• 缓存包注册表，用于处理生成的缓存包
• 适用于各种用例的缓存过期计算器（查询构建器、查询结果等）
• 事件监听器，可根据注册的页面缓存包覆盖页面缓存过期
• 兼容TYPO3 11.5 LTS、12.4 LTS和13.1

🔥 安装

Composer

composer require cpsit/typo3-cache-bags

TER

或者，您也可以通过TYPO3扩展仓库（TER）下载此扩展。

⚡ 使用方法

缓存包

一个缓存包可以看作是针对特定缓存作用域的一些类型的数据集合，例如针对当前页面（前端相关缓存）。它用于在给定作用域内控制缓存行为，例如通过定义自定义缓存标签或明确的过期日期。

目前支持的缓存包如下

提示

您还可以通过实现Cache\Bag\CacheBag来添加自己的缓存包。

以下是一个如何为给定页面生成新的PageCacheBag的示例

use CPSIT\Typo3CacheBags;

$pageId = 72;
$expirationDate = new DateTimeImmutable('tomorrow midnight');

$cacheBag = Typo3CacheBags\Cache\Bag\PageCacheBag::forPage($pageId, $expirationDate);

缓存包注册表

为了实际使用生成的缓存包，每个包都必须在全局的Cache\Bag\CacheBagRegistry中注册。此注册表定义为单例实例，并在运行时存储所有注册的缓存包。

应通过依赖注入使用CacheBagRegistry，或者如果无法使用DI，则通过使用GeneralUtility::makeInstance()

use CPSIT\Typo3CacheBags;
use TYPO3\CMS\Core;

$cacheBag = Typo3CacheBags\Cache\Bag\PageCacheBag::forPage(72);
$cacheBagRegistry = Core\Utility\GeneralUtility::makeInstance(Typo3CacheBags\Cache\Bag\CacheBagRegistry::class);
$cacheBagRegistry->add($cacheBag);

派发的事件

向注册表中添加新的CacheBag时，会派发一个CacheBagRegisteredEvent。例如，它用于将缓存标签应用于当前前端请求（使用提供的PageCacheBagRegisteredEventListener）。

获取最近的过期日期

基于所有注册的缓存包，注册表能够计算给定缓存作用域的最近过期日期（如果任何缓存包提供了过期日期）

use CPSIT\Typo3CacheBags;
use TYPO3\CMS\Core;

$cacheBagRegistry = Core\Utility\GeneralUtility::makeInstance(Typo3CacheBags\Cache\Bag\CacheBagRegistry::class);
$expirationDate = $cacheBagRegistry->getExpirationDate(Typo3CacheBags\Enum\CacheScope::Pages);

此功能用于将过期日期应用于当前前端页面缓存（使用随软件提供的PageCacheLifetimeEventListener（TYPO3 ≥ v12版本）和PageCacheTimeoutHook（TYPO3 v11版本））。

缓存过期计算器

如前所述，缓存包还可以存储目标缓存条目的过期日期。该扩展包含一个Cache\CacheExpirationCalculator，可用于计算过期日期。计算基于多种输入方法。目前，以下方法可用：

• 基于 Extbase查询或查询结果 的计算
• 基于 QueryBuilder 实例的计算
• 基于初始化的 关系处理器 的计算

use CPSIT\Typo3CacheBags;
use TYPO3\CMS\Core;

// Use DI instead, calculator is *NOT* publicly available in the service container!
$cacheExpirationCalculator = Core\Utility\GeneralUtility::makeInstance(Typo3CacheBags\Cache\Expiration\CacheExpirationCalculator::class);
$connectionPool = Core\Utility\GeneralUtility::makeInstance(Core\Database\ConnectionPool::class);

$queryBuilder = $connectionPool->getQueryBuilderForTable('pages');
$queryBuilder->select('*')
    ->from('pages')
    ->where(
        $queryBuilder->expr()->or(
            $queryBuilder->expr()->eq('uid', $queryBuilder->createNamedParameter(72, Core\Database\Connection::PARAM_INT)),
            $queryBuilder->expr()->eq('pid', $queryBuilder->createNamedParameter(72, Core\Database\Connection::PARAM_INT)),
        ),
    )
;

$expirationDate = $cacheExpirationCalculator->forQueryBuilder('pages', $queryBuilder);
$cacheBag = Typo3CacheBags\Cache\Bag\PageCacheBag::forPage(72, $expirationDate);

完整示例

缓存包的典型用例是前端作用域中自定义记录的列表和详情视图。以下是一个完整示例，展示如何在自定义表的列表和详情视图中使用PageCacheBag。

use CPSIT\Typo3CacheBags;
use Psr\Http\Message;
use TYPO3\CMS\Core;
use TYPO3\CMS\Extbase;

final class BlogController extends Extbase\Mvc\Controller\ActionController
{
    public function __construct(
        private readonly BlogRepository $blogRepository,
        private readonly Typo3CacheBags\Cache\Bag\CacheBagRegistry $cacheBagRegistry,
        private readonly Typo3CacheBags\Cache\Expiration\CacheExpirationCalculator $cacheExpirationCalculator,
    ) {}

    public function listAction(): Message\ResponseInterface
    {
        /** @var Extbase\Persistence\QueryResultInterface<Blog> $blogArticles */
        $blogArticles = $this->blogRepository->findAll();

        // Create cache bag with reference to the queried table
        // and apply the calculated expiration date of all queried blog articles
        $cacheBag = Typo3CacheBags\Cache\Bag\PageCacheBag::forTable(
            Blog::TABLE_NAME,
            $this->cacheExpirationCalculator->forQueryResult(Blog::TABLE_NAME, $blogArticles),
        );

        // Add cache bag to registry
        $this->cacheBagRegistry->add($cacheBag);

        $this->view->assign('articles', $blogArticles);

        return $this->htmlResponse();
    }

    public function detailAction(Blog $article): Message\ResponseInterface
    {
        // Create cache bag with reference to the current article
        // and apply the article's endtime as cache expiration date
        $cacheBag = Typo3CacheBags\Cache\Bag\PageCacheBag::forRecord(
            Blog::TABLE_NAME,
            $article->getUid(),
            $article->getEndtime(),
        );

        // Add cache bag to registry
        $this->cacheBagRegistry->add($cacheBag);

        $this->view->assign('article', $article);

        return $this->htmlResponse();
    }
}

🧑‍💻 贡献

请参阅CONTRIBUTING.md。

💎 致谢

扩展图标（容器）是修改自TYPO3核心的原始actions-container图标，原始许可证为MIT许可证。

⭐ 许可证

此项目根据GNU通用公共许可证2.0（或更高版本）进行许可。