<?php

declare(strict_types=1);

namespace App\Framework\Cache;

use App\Framework\Core\ValueObjects\Duration;

interface Cache
{
    /**
     * Get cache items for one or more identifiers (keys, tags, prefixes)
     * Returns CacheResult with all matching items (hits and misses)
     */
    public function get(CacheIdentifier ...$identifiers): CacheResult;

    /**
     * Set one or more cache items
     * Each CacheItem can have its own TTL
     */
    public function set(CacheItem ...$items): bool;

    /**
     * Check if one or more identifiers exist in cache
     * @return array<string, bool> Identifier string => exists
     */
    public function has(CacheIdentifier ...$identifiers): array;

    /**
     * Remove cache items by identifiers (keys, tags, prefixes)
     * Supports batch operations and different identifier types
     */
    public function forget(CacheIdentifier ...$identifiers): bool;

    /**
     * Clear all cache items
     */
    public function clear(): bool;

    /**
     * Führt Callback aus, wenn Wert nicht im Cache ist ("Remember"-Pattern)
     * und cached das Ergebnis für die gewünschte Zeit
     */
    public function remember(CacheKey $key, callable $callback, ?Duration $ttl = null): CacheItem;
}