<?php
/**
 * Cache Interface
 *
 * Defines the contract for cache implementations.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Contracts
 * @since       2.0.0
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Contracts;

/**
 * Contract for cache implementations.
 *
 * Implementations should handle key prefixing, serialization,
 * and TTL management internally.
 *
 * @since 2.0.0
 */
interface CacheInterface
{
    /**
     * Retrieve a value from cache.
     *
     * @param string $key     Cache key.
     * @param mixed  $default Default value if key not found.
     *
     * @return mixed Cached value or default.
     */
    public function get(string $key, mixed $default = null): mixed;

    /**
     * Store a value in cache.
     *
     * @param string $key   Cache key.
     * @param mixed  $value Value to cache.
     * @param int    $ttl   Time to live in seconds.
     *
     * @return bool True on success.
     */
    public function set(string $key, mixed $value, int $ttl = 3600): bool;

    /**
     * Check if a key exists in cache.
     *
     * @param string $key Cache key.
     *
     * @return bool True if key exists and is not expired.
     */
    public function has(string $key): bool;

    /**
     * Remove a key from cache.
     *
     * @param string $key Cache key.
     *
     * @return bool True on success.
     */
    public function forget(string $key): bool;

    /**
     * Remove all keys matching a prefix.
     *
     * Deletes all cache entries whose keys start with the given prefix.
     * Useful for invalidating related cache entries (e.g., all user-specific cache).
     *
     * @param string $prefix Key prefix to match.
     *
     * @return int Number of keys removed.
     */
    public function forgetByPrefix(string $prefix): int;

    /**
     * Get or set a cached value.
     *
     * If key exists, returns cached value. Otherwise, executes callback,
     * caches the result, and returns it.
     *
     * @param string   $key      Cache key.
     * @param int      $ttl      Time to live in seconds.
     * @param callable $callback Callback returning value to cache.
     *
     * @return mixed Cached or computed value.
     */
    public function remember(string $key, int $ttl, callable $callback): mixed;

    /**
     * Get or set a cached value with no expiration.
     *
     * @param string   $key      Cache key.
     * @param callable $callback Callback returning value to cache.
     *
     * @return mixed Cached or computed value.
     */
    public function rememberForever(string $key, callable $callback): mixed;

    /**
     * Remove all cached values.
     *
     * @return bool True on success.
     */
    public function flush(): bool;

    /**
     * Get cache statistics.
     *
     * Returns information about cache performance including hits, misses,
     * writes, runtime entry count, and hit ratio.
     *
     * @return array{hits: int, misses: int, writes: int, runtime_count: int, hit_ratio: float}
     */
    public function getStats(): array;
}
