<?php
/**
 * BookiFlex Core
 *
 * @package    BookiFlex
 * @subpackage Core
 * @author     BookiFlex
 * @copyright  Copyright (c) 2025 BookiFlex
 * @license    GPL-2.0-or-later
 *
 * @link       https://bookiflex.com
 */

declare(strict_types=1);

namespace BookiFlex\Core\Infrastructure\Storage;

defined( 'ABSPATH' ) || exit;

/**
 * Repository interface for temporary cache storage.
 *
 * Provides abstraction over WordPress transients API for storing
 * temporary data with expiration time.
 */
interface CacheRepositoryInterface
{
    /**
     * Get a cached value.
     *
     * @param string $key Cache key (will be prefixed automatically)
     * @param mixed $default Default value if cache doesn't exist or expired
     * @return mixed Cached value or default
     */
    public function get(string $key, mixed $default = null): mixed;

    /**
     * Set a cached value with TTL.
     *
     * @param string $key Cache key (will be prefixed automatically)
     * @param mixed $value Value to cache
     * @param int $ttl Time to live in seconds (default: 3600)
     * @return bool True on success, false on failure
     */
    public function set(string $key, mixed $value, int $ttl = 3600): bool;

    /**
     * Delete a cached value.
     *
     * @param string $key Cache key (will be prefixed automatically)
     * @return bool True on success, false on failure
     */
    public function delete(string $key): bool;

    /**
     * Check if a cached value exists and is not expired.
     *
     * @param string $key Cache key (will be prefixed automatically)
     * @return bool True if cache exists and not expired, false otherwise
     */
    public function has(string $key): bool;

    /**
     * Flush all cached values with this repository's prefix.
     *
     * @return bool True on success, false on failure
     */
    public function flush(): bool;
}
