<?php

declare(strict_types=1);

/**
 * This file is part of CodeIgniter 4 framework.
 *
 * (c) CodeIgniter Foundation <admin@codeigniter.com>
 *
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 */

namespace CodeIgniter\Cache;

use Closure;

interface CacheInterface
{
 /**
 * Takes care of any handler-specific setup that must be done.
 */
 public function initialize(): void;

 /**
 * Attempts to fetch an item from the cache store.
 *
 * @param string $key Cache item name
 */
 public function get(string $key): mixed;

 /**
 * Saves an item to the cache store.
 *
 * @param string $key Cache item name
 * @param mixed $value The data to save
 * @param int $ttl Time To Live, in seconds (default 60)
 *
 * @return bool Success or failure
 */
 public function save(string $key, mixed $value, int $ttl = 60): bool;

 /**
 * Attempts to get an item from the cache, or executes the callback
 * and stores the result on cache miss.
 *
 * @param string $key Cache item name
 * @param int $ttl Time To Live, in seconds
 * @param Closure(): mixed $callback Callback executed on cache miss
 */
 public function remember(string $key, int $ttl, Closure $callback): mixed;

 /**
 * Deletes a specific item from the cache store.
 *
 * @param string $key Cache item name
 *
 * @return bool Success or failure
 */
 public function delete(string $key): bool;

 /**
 * Deletes items from the cache store matching a given pattern.
 *
 * @param string $pattern Cache items glob-style pattern
 *
 * @return int Number of deleted items
 */
 public function deleteMatching(string $pattern): int;

 /**
 * Performs atomic incrementation of a raw stored value.
 *
 * @param string $key Cache ID
 * @param int $offset Step/value to increase by
 */
 public function increment(string $key, int $offset = 1): bool|int;

 /**
 * Performs atomic decrementation of a raw stored value.
 *
 * @param string $key Cache ID
 * @param int $offset Step/value to increase by
 */
 public function decrement(string $key, int $offset = 1): bool|int;

 /**
 * Will delete all items in the entire cache.
 *
 * @return bool Success or failure
 */
 public function clean(): bool;

 /**
 * Returns information on the entire cache.
 *
 * The information returned and the structure of the data
 * varies depending on the handler.
 *
 * @return array<array-key, mixed>|false|object|null
 */
 public function getCacheInfo(): array|false|object|null;

 /**
 * Returns detailed information about the specific item in the cache.
 *
 * @param string $key Cache item name.
 *
 * @return array<string, mixed>|null Returns null if the item does not exist, otherwise array<string, mixed>
 * with at least the 'expire' key for absolute epoch expiry (or null).
 */
 public function getMetaData(string $key): ?array;

 /**
 * Determines if the driver is supported on this system.
 */
 public function isSupported(): bool;
}