<?php

declare(strict_types=1);

namespace ContextPaging;

/**
 * Interface for caching arbitrary data.
 */
interface CacheInterface
{
    /**
     * Get a value from the cache.
     *
     * @param string $key The cache key
     * @return mixed|null The cached value or null if not found
     */
    public function get(string $key): mixed;

    /**
     * Set a value in the cache.
     *
     * @param string $key The cache key
     * @param mixed $value The value to cache (must be serializable)
     * @param int|null $ttl Optional TTL in seconds
     */
    public function set(string $key, mixed $value, ?int $ttl = null): void;

    /**
     * Check if a key exists.
     *
     * @param string $key The cache key
     * @return bool
     */
    public function has(string $key): bool;

    /**
     * Delete a key from the cache.
     *
     * @param string $key The cache key
     */
    public function delete(string $key): void;

    /**
     * Clear all keys with the configured prefix.
     */
    public function clear(): void;
}
