# 缓存

storh 内置轻量缓存后端，无需运行时依赖：

```php
use Storh\Cache;
use Storh\CacheValidation;

$docs = new Storh\DocStore($root, 'pages', cache: Cache::memory(maxEntries: 10000));
$docs = new Storh\DocStore($root, 'pages', cache: Cache::apcu('storh.pages'));
$docs = new Storh\DocStore(
    $root,
    'pages',
    cache: Cache::memory(maxEntries: 100000, maxBytes: 96 * 1024 * 1024),
    cache_validation: CacheValidation::TRUST
);
```

缓存层：

- 已解码的 DocStore 记录
- 缺失记录的负查找结果
- 分段日志清单
- 稀疏分段索引

验证模式：

- `CacheValidation::STAT`：验证是否存在、修改时间和大小。
- `CacheValidation::HASH`：验证是否存在、修改时间、大小和内容哈希。
- `CacheValidation::TRUST`：缓存命中时跳过文件系统验证，并信任当前的 storh 实例或共享缓存后端会发布显式的 storh 写入。

`STAT` 是默认的快速验证模式。如果每次缓存命中都必须验证文件内容，包括修改时间未变但内容大小相同的写入，请使用 `HASH`。`STAT` 无法检测同时保留修改时间和大小的外部内容更改。对于单进程或共享缓存工作负载，`TRUST` 是最快的模式；它有意不检测在 storh 之外更改的文件。

`Cache::memory()` 同时受条目数量和字节数限制。如果未提供 `maxBytes`，则会根据 PHP 的 `memory_limit` 推算预算。

`Cache::apcu()` 是可选项。如果当前 SAPI 无法使用 APCu 或已将其禁用，它会作为空操作后端运行。

## 何时挂载缓存后端

`DocStore` 始终会为已读取或写入的记录保留小型实例内缓存，并按配置的模式进行验证。挂载后端会添加一个生命周期超出实例的缓存：对于会重新打开存储的长时间运行进程，`Cache::memory()` 很有帮助；`Cache::apcu()` 则可在多个 PHP-FPM 请求之间共享已解码记录。[基准测试](https://storh.inline0.dev/zh/docs/benchmarks)测得，内存后端的冷读取耗时约为 83 µs，而经过 STAT 验证的热缓存命中耗时约为 6 µs。