Caching

public static function remember(string $name, string $key, int $ttl, callable $producer);
public static function getInstance(): self;

// $config: a string is the store name, an array accepts 'name', 'path', 'extension'.
public function __construct($config = []);

public function store($key, $data, $expiration = 86400): bool;
public function retrieve($key, $timestamp = false);
public function isCached($key): bool;
public function erase($key): self;
public function eraseExpired(): int;
public function eraseAll(): self;
public function clear($keys = []): void;

// Fine: an array, and the type says so.
Cache::remember('website', 'tld_requirements', 3600, fn (): array => self::build_requirements());

// Fine: a rendered string.
Cache::remember('website', 'sitemap_' . $lang, 3600, fn (): string => $this->build($lang));

// Fine: several captured values, block body.
Cache::remember('website', 'plans_' . $categoryId . '_' . $ucid, 3600, function () use ($categoryId, $ucid): array {
    $rows = self::plans($categoryId);

    return self::decorate($rows, $ucid);
});

// Broken: null is written but reads back as "missing", so the producer runs
// on every request forever and the cache silently does nothing.
Cache::remember('website', 'maybe_nothing', 3600, fn () => null);

static function catalog_plans(int $categoryId, string $type, string $layout = 'grid'): array
{
    $ucid = Money::selected();

    // Prices depend on the currency and labels on the language, so the key carries
    // both, plus everything that selects the rows.
    $plans = Cache::remember('website', 'plans_' . $categoryId . '_' . $type . '_' . $layout . '_' . $ucid . '_' . Language::selected(), 3600,
        fn (): array => self::catalog_plans_fresh($categoryId, $type, $layout, $ucid));

    // Stock moves with every order, so it is refreshed live over the cached payload
    // rather than being part of it.
    if ($plans) {
        $stocks = self::catalog_stocks(array_map(fn ($p) => (int) $p["id"], $plans));
        foreach ($plans as &$plan) {
            $stock = trim((string) ($stocks[(int) $plan["id"]] ?? ''));
            $plan["in_stock"] = ($stock === '' || (int) $stock > 0);
        }
        unset($plan);
    }

    // Hooks run on EVERY request, so they sit outside the producer. The context goes
    // into a variable first: runRefs takes all of its arguments by reference.
    $ctx = ['category_id' => $categoryId, 'type' => $type, 'layout' => $layout];
    Hook::runRefs('filter:product.catalog_plans', $plans, $ctx);

    return $plans;
}

trait AdminManageWebsite
{
    public function save_menu_changes(Operation $operation): bool
    {
        $operation->demo();

        // ... write the rows ...

        // Targeted: only the 'menus' store, addressed by store name.
        Cache::getInstance()->clear(['menus']);

        return $operation->output(['status' => "successful"]);
    }
}

// Removing a single entry is the other method, and it throws on a miss.
$cache = new Cache('website');
if ($cache->isCached('plans_5_hosting_grid_1_en')) $cache->erase('plans_5_hosting_grid_1_en');