# Caching

storh dilengkapi backend cache kecil tanpa dependensi runtime:

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

Lapisan cache:

- record DocStore yang telah didekode
- pencarian negatif untuk record yang tidak ditemukan
- manifest log tersegmentasi
- indeks segmen jarang

Mode validasi:

- `CacheValidation::STAT`: validasi keberadaan, mtime, dan ukuran.
- `CacheValidation::HASH`: validasi keberadaan, mtime, ukuran, dan hash konten.
- `CacheValidation::TRUST`: lewati validasi sistem file saat cache hit dan percayai
  instans storh saat ini atau backend cache bersama untuk menerbitkan penulisan storh eksplisit.

`STAT` adalah mode validasi cepat bawaan. Gunakan `HASH` jika setiap cache hit juga harus
memvalidasi konten file, termasuk penulisan berukuran sama yang mempertahankan mtime.
`STAT` tidak dapat mendeteksi perubahan konten dari luar yang mempertahankan mtime dan ukuran.
`TRUST` adalah mode tercepat untuk beban kerja satu proses atau cache bersama;
mode ini sengaja tidak mendeteksi file yang diubah di luar storh.

`Cache::memory()` dibatasi oleh jumlah entri dan ukuran byte. Jika `maxBytes` tidak
diberikan, anggaran dihitung berdasarkan PHP milik `memory_limit`.

`Cache::apcu()` bersifat opsional. Jika APCu tidak tersedia atau dinonaktifkan untuk
SAPI saat ini, backend ini tidak melakukan apa pun.

## Kapan menambahkan salah satunya

`DocStore` selalu menyimpan cache kecil per instans untuk record yang sudah dibaca
atau ditulisnya, dengan validasi sesuai mode yang dikonfigurasi. Menambahkan backend berarti menyediakan cache yang bertahan lebih lama daripada instans: `Cache::memory()` membantu proses berjalan lama yang membuka ulang store, sedangkan `Cache::apcu()` berbagi record yang telah didekode di antara permintaan PHP-FPM. [tolok ukur](https://storh.inline0.dev/id/docs/benchmarks) mengukur backend memori sekitar 83 µs per pembacaan cold dibandingkan 6 µs per cache hit warm yang divalidasi STAT.