<?php

declare(strict_types=1);

namespace App\Framework\Cache\Strategies;

use App\Framework\Cache\CacheKey;
use App\Framework\Core\ValueObjects\Duration;

/**
 * Unified Cache Strategy Interface
 *
 * Allows implementing various caching strategies that can be composed together
 * in SmartCache for enhanced cache behavior.
 */
interface CacheStrategy
{
    /**
     * Called on every cache access (hit or miss)
     *
     * @param CacheKey $key The cache key being accessed
     * @param bool $isHit Whether the access was a cache hit
     * @param Duration|null $retrievalTime Time taken to retrieve the value
     */
    public function onCacheAccess(CacheKey $key, bool $isHit, ?Duration $retrievalTime = null): void;

    /**
     * Called when setting a cache item - can modify the TTL
     *
     * @param CacheKey $key The cache key being set
     * @param mixed $value The value being cached
     * @param Duration|null $originalTtl The original TTL requested
     * @return Duration The TTL to actually use (can be modified by strategy)
     */
    public function onCacheSet(CacheKey $key, mixed $value, ?Duration $originalTtl): Duration;

    /**
     * Called when a cache item is forgotten/deleted
     *
     * @param CacheKey $key The cache key being deleted
     */
    public function onCacheForget(CacheKey $key): void;

    /**
     * Get strategy-specific statistics and metrics
     *
     * @return array Strategy statistics
     */
    public function getStats(): array;

    /**
     * Get the strategy name/identifier
     *
     * @return string Strategy name
     */
    public function getName(): string;

    /**
     * Clear all strategy data and reset state
     */
    public function clear(): void;

    /**
     * Check if strategy is enabled/active
     *
     * @return bool Whether strategy is active
     */
    public function isEnabled(): bool;
}
