<?php

namespace App\Services\Cache;

use Closure;

interface CacheServiceInterface
{
    public const TTL_SHORT  = 'short';   // 5 minutes
    public const TTL_MEDIUM = 'medium';  // 1 hour
    public const TTL_LONG   = 'long';    // 24 hours

    /**
     * Return cached value or execute callback and store the result.
     * Logs HIT / MISS to debug channel.
     *
     * @param string[] $tags  Optional tag list (only applied when driver supports tagging)
     */
    public function remember(
        string $key,
        Closure $callback,
        string $ttl = self::TTL_MEDIUM,
        array $tags = [],
    ): mixed;

    /**
     * Store a value unconditionally.
     *
     * @param string[] $tags
     */
    public function put(
        string $key,
        mixed $value,
        string $ttl = self::TTL_MEDIUM,
        array $tags = [],
    ): void;

    public function get(string $key, mixed $default = null): mixed;

    public function forget(string $key): void;

    /**
     * Invalidate all cache entries belonging to a module.
     *
     * Uses Cache::tags()->flush() when the driver supports tagging (Redis, Memcached),
     * falls back to a Redis SCAN-based deletion otherwise.
     */
    public function clearByModule(string $module): void;
}