<?php

namespace Kirby\Cache;

/**
 * Cache foundation
 * This abstract class is used as
 * foundation for other cache drivers
 * by extending it
 *
 * @package   Kirby Cache
 * @author    Bastian Allgeier <bastian@getkirby.com>
 * @link      https://getkirby.com
 * @copyright Bastian Allgeier
 * @license   https://opensource.org/licenses/MIT
 */
abstract class Cache
{
	/**
	 * Stores all options for the driver
	 * @var array
	 */
	protected $options = [];

	/**
	 * Sets all parameters which are needed to connect to the cache storage
	 *
	 * @param array $options
	 */
	public function __construct(array $options = [])
	{
		$this->options = $options;
	}

	/**
	 * Writes an item to the cache for a given number of minutes and
	 * returns whether the operation was successful;
	 * this needs to be defined by the driver
	 *
	 * <code>
	 *   // put an item in the cache for 15 minutes
	 *   $cache->set('value', 'my value', 15);
	 * </code>
	 *
	 * @param string $key
	 * @param mixed $value
	 * @param int $minutes
	 * @return bool
	 */
	abstract public function set(string $key, $value, int $minutes = 0): bool;

	/**
	 * Adds the prefix to the key if given
	 *
	 * @param string $key
	 * @return string
	 */
	protected function key(string $key): string
	{
		if (empty($this->options['prefix']) === false) {
			$key = $this->options['prefix'] . '/' . $key;
		}

		return $key;
	}

	/**
	 * Internal method to retrieve the raw cache value;
	 * needs to return a Value object or null if not found;
	 * this needs to be defined by the driver
	 *
	 * @param string $key
	 * @return \Kirby\Cache\Value|null
	 */
	abstract public function retrieve(string $key);

	/**
	 * Gets an item from the cache
	 *
	 * <code>
	 *   // get an item from the cache driver
	 *   $value = $cache->get('value');
	 *
	 *   // return a default value if the requested item isn't cached
	 *   $value = $cache->get('value', 'default value');
	 * </code>
	 *
	 * @param string $key
	 * @param mixed $default
	 * @return mixed
	 */
	public function get(string $key, $default = null)
	{
		// get the Value
		$value = $this->retrieve($key);

		// check for a valid cache value
		if (!is_a($value, 'Kirby\Cache\Value')) {
			return $default;
		}

		// remove the item if it is expired
		if ($value->expires() > 0 && time() >= $value->expires()) {
			$this->remove($key);
			return $default;
		}

		// return the pure value
		return $value->value();
	}

	/**
	 * Calculates the expiration timestamp
	 *
	 * @param int $minutes
	 * @return int
	 */
	protected function expiration(int $minutes = 0): int
	{
		// 0 = keep forever
		if ($minutes === 0) {
			return 0;
		}

		// calculate the time
		return time() + ($minutes * 60);
	}

	/**
	 * Checks when an item in the cache expires;
	 * returns the expiry timestamp on success, null if the
	 * item never expires and false if the item does not exist
	 *
	 * @param string $key
	 * @return int|null|false
	 */
	public function expires(string $key)
	{
		// get the Value object
		$value = $this->retrieve($key);

		// check for a valid Value object
		if (!is_a($value, 'Kirby\Cache\Value')) {
			return false;
		}

		// return the expires timestamp
		return $value->expires();
	}

	/**
	 * Checks if an item in the cache is expired
	 *
	 * @param string $key
	 * @return bool
	 */
	public function expired(string $key): bool
	{
		$expires = $this->expires($key);

		if ($expires === null) {
			return false;
		} elseif (!is_int($expires)) {
			return true;
		} else {
			return time() >= $expires;
		}
	}

	/**
	 * Checks when the cache has been created;
	 * returns the creation timestamp on success
	 * and false if the item does not exist
	 *
	 * @param string $key
	 * @return int|false
	 */
	public function created(string $key)
	{
		// get the Value object
		$value = $this->retrieve($key);

		// check for a valid Value object
		if (!is_a($value, 'Kirby\Cache\Value')) {
			return false;
		}

		// return the expires timestamp
		return $value->created();
	}

	/**
	 * Alternate version for Cache::created($key)
	 *
	 * @param string $key
	 * @return int|false
	 */
	public function modified(string $key)
	{
		return static::created($key);
	}

	/**
	 * Determines if an item exists in the cache
	 *
	 * @param string $key
	 * @return bool
	 */
	public function exists(string $key): bool
	{
		return $this->expired($key) === false;
	}

	/**
	 * Removes an item from the cache and returns
	 * whether the operation was successful;
	 * this needs to be defined by the driver
	 *
	 * @param string $key
	 * @return bool
	 */
	abstract public function remove(string $key): bool;

	/**
	 * Flushes the entire cache and returns
	 * whether the operation was successful;
	 * this needs to be defined by the driver
	 *
	 * @return bool
	 */
	abstract public function flush(): bool;

	/**
	 * Returns all passed cache options
	 *
	 * @return array
	 */
	public function options(): array
	{
		return $this->options;
	}
}