README

这是一个专门为网页缓存设计的缓存库。虽然在格式上不遵循PSR-6，但某些功能可能相似。它不是作为其他缓存解决方案（如Symfony的Cache）的替代品，因为它是一个针对特定领域的解决方案，而不是一个更通用的解决方案。

为什么？

尽管缓存似乎是一个长期解决的问题，有许多好的解决方案，但我发现有两个问题，它们并没有满足我提供一致网页服务的愿望。

1. 如果服务于页面的代码库发生变化，它不会自动使缓存的页面版本失效，这意味着可能会提供过时的内容。
2. 如果我要提供相同的头部信息，我需要将它们单独缓存，并通过额外的逻辑将它们与缓存的内容联系起来。有些人可能会说这些问题很小，他们可能是对的，这些问题不太可能真正引起问题，但对我来说，这意味着除非我添加与之前使用的Symfony\Cache配套的额外逻辑，否则我将以新的头部信息提供过时的内容，这可能会降低用户体验。我不想这样。

是什么？

这就是我决定编写自己的解决方案的原因，该解决方案专门用于网页。第一个问题通过计算代码库的版本来解决，如下所示

$usedFiles = get_included_files();
$this->version = count($usedFiles).'.'.max(max(array_map('filemtime', array_filter($usedFiles, 'is_file'))),

然后将此版本存储在每个指定键的缓存中。当从缓存中获取数据时，它会与当前版本进行匹配，如果不匹配，则被视为缓存未命中。这不是100%的保证，但由于我有一个处理所有页面生成的“网关”文件，所以对我来说效果很好。第二个问题通过缓存与数据一起发送的头部信息来解决。一旦检索到数据，相同的头部信息将再次发送。不仅如此，它还具有其他可能有用的功能

1. 可选的压缩缓存中的数据以减少占用空间
2. 如果可用，则使用来自HTTP20库的zEcho函数直接输出（否则将使用常规的echo）
3. 使用哈希验证缓存以减少提供损坏缓存的几率
4. 用于减轻缓存攻击的技术（至少在某种程度上）
5. 自动尝试使用APCU或文件存储。由于我没有适当的测试基础设施，不支持Memcache等。
6. 在失败的情况下使用瞬态，以便您的网页仍然可以显示（通常是）

如何？

以下是一个简单的示例，说明我是如何使用它的。向下滚动以了解更多关于函数的详细信息。

#Create HTMLCache object
$HTMLCache = (new \Simbiat\HTMLCache($siteconfig['cachedir'].'html/'));
#Attempt to use cache
$HTMLCache->get('', true, true, true);
#Do some processing in case cache was not hit, to get $output
#Save to cache and output directly
if ($uri[1] === 'statistics') {
    $HTMLCache->set($output, '', 604800, 600, true, true);
} elseif ($uri[1] === 'achievement') {
    $HTMLCache->set($output, '', 259200, 600, true, true);
}
#Output page if not required to cache
(new \Simbiat\HTTP20\Common)->zEcho($output);

使用说明

构造函数

__construct(string $filesPool = '', bool $apcu = false, int $maxRandom = 1)

在创建对象时，您可以使用$filesPool指定缓存文件的存储路径。如果为空，这将让类知道您不想使用文件存储进行缓存。在这种情况下，您需要显式启用APCU缓存，将$apcu设置为true。默认情况下设置为false，因为您可能拥有的资源可能有限。为了减轻缓存攻击，类在验证时将过期日期减少随机值（从0到$maxRandom，默认为1分钟）。您可以调整此数值或使用0来禁用此功能（不建议）。

设置

set(string $string, string $key ='', int $ttl = 60, int $grace = 100, bool $zip = true, bool $direct = true, string $cacheStrat = '')

使用set写入缓存。$string是唯一必填的值。由于该类是为HTML页面设计的，因此我们限制值的类型仅为string。$key是存储值时使用的ID的可选值。如果为空，则使用当前REQUEST_URI（如果为空，则使用index.php）。无论如何，值都将进行散列以确保一致性。$ttl是缓存的生存时间（time to live）。在它过期后，值将被视为过时。默认为60，即1小时。$grace是用于帮助处理缓存冲击的可选宽限期。当缓存命中成功，但已过期时，类会将过期值更新为time()+$grace并将$grace设置为0。这有助于处理并发请求，这样它们在初始命中更新缓存后，在过期后额外几秒钟内仍会接收到过时的数据。默认为1分钟。$zip将压缩页面的主体和头部以节省空间。由于当前的处理器性能和平均HTML页面大小，这是一个非常快速的操作，可以帮助你在内存和磁盘上缓存更多内容。如果你想禁用它，可以将其设置为false。$direct如果设置为true，将在写入缓存后立即输出网页。由于我们正在处理网页，在生成页面后没有太多理由再进行其他操作，但你可以禁用此行为，并接收表示函数结果的布尔值。$cacheStrat用于配置Cache-Control头部（使用适当的功能），如果你正在使用zEcho。此值也将被缓存。

获取

get(string $key = '', bool $scriptVersion = true, bool $direct = true, bool $staleReturn = false)

使用get获取缓存数据。$key是存储值时使用的ID的可选值。如果为空，则使用当前REQUEST_URI（如果为空，则使用index.php）。无论如何，值都将进行散列以确保一致性。$scriptVersion如果设置为true，将强制验证代码库版本，如上所述。由于这更多的是个人偏好，你可以禁用此功能。$direct如果设置为true，将在获取页面时立即输出网页。由于我们正在处理网页，没有太多理由要禁用此功能，但你也可以这样做，并接收表示所有缓存数据的数组。不过，我认为这除了在类内部外可能没有太大用处。$staleReturn如果设置为true，将允许在生成新内容的同时手动提供过时内容。在某种程度上，类似于Cache-Control头部中的stale-while-revalidate。

缓存输出

cacheOutput(array $data, bool $exit = true)

用于手动输出get返回的数据。$data是get返回的数组。$exit标志允许在输出后取消自动退出（默认），以防你计划在之后进行其他操作（当使用get与$staleReturn = true时非常有用）。

删除

delete(string $key = '')

使用delete删除缓存项。$key是存储值时使用的ID的可选值。如果为空，则使用当前REQUEST_URI（如果为空，则使用index.php）。无论如何，值都将进行散列以确保一致性。

垃圾回收

gc(int $maxAge = 60, int $maxSize = 1024)

这个垃圾回收函数明确地移除超过 $maxAge 分钟（默认为60分钟）的老条目，或者直到总大小小于 $maxSize 兆字节（MB）的所有最老条目。它会检查修改时间，这意味着只有连续未使用天数达到一定数量的缓存条目会受到影響。你应该根据项目中最长的缓存时间来调整这个值。或者，你可以通过将值设置为0来禁用这个功能。当使用文件存储时，它还会删除空目录。