# Armazenamento em cache

storh inclui backends de cache pequenos e nenhuma dependência de execução:

```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
);
```

Camadas de cache:

- registros DocStore decodificados
- consultas negativas para registros ausentes
- manifestos do log segmentado
- índices esparsos de segmentos

Modos de validação:

- `CacheValidation::STAT`: validar existência, mtime e tamanho.
- `CacheValidation::HASH`: validar existência, mtime, tamanho e hash do conteúdo.
- `CacheValidation::TRUST`: ignorar a validação do sistema de arquivos em acertos e confiar na
  instância storh atual ou em um backend de cache compartilhado para publicar gravações storh explícitas.

`STAT` é o modo rápido de validação padrão. Use `HASH` quando cada acerto de cache também precisar
validar o conteúdo dos arquivos, inclusive gravações do mesmo tamanho que preservem o mtime.
`STAT` não detecta uma alteração externa no conteúdo que preserve tanto o mtime quanto o
tamanho. `TRUST` é o modo mais rápido para cargas de trabalho de processo único ou cache compartilhado;
intencionalmente não detecta arquivos alterados fora de storh.

`Cache::memory()` tem limites por quantidade de entradas e por bytes. Quando `maxBytes` não é
fornecido, o orçamento é calculado com base em `memory_limit` de PHP.

`Cache::apcu()` é opcional. Se APCu não estiver disponível ou estiver desativado para o SAPI atual,
ele funciona como um backend sem operação.

## Quando conectar um backend

`DocStore` mantém sempre pequenos caches por instância para registros que já leu ou gravou, validados conforme o modo configurado. Anexar um backend adiciona um cache que sobrevive à instância: `Cache::memory()` ajuda processos de longa duração que reabrem armazenamentos, e `Cache::apcu()` compartilha registros decodificados entre solicitações PHP-FPM. Os [benchmarks](https://storh.inline0.dev/pt/docs/benchmarks) medem o backend de memória em cerca de 83 µs por leitura fria, contra 6 µs por leitura quente validada por STAT.