initial commit

kirby/src/Cache/ApcuCache.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Kirby\Cache;
+
+use APCUIterator;
+
+/**
+ * APCu Cache Driver
+ *
+ * @package   Kirby Cache
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class ApcuCache extends Cache
+{
+	/**
+	 * Returns whether the cache is ready to
+	 * store values
+	 */
+	public function enabled(): bool
+	{
+		return apcu_enabled();
+	}
+
+	/**
+	 * Determines if an item exists in the cache
+	 */
+	public function exists(string $key): bool
+	{
+		return apcu_exists($this->key($key));
+	}
+
+	/**
+	 * Flushes the entire cache and returns
+	 * whether the operation was successful
+	 */
+	public function flush(): bool
+	{
+		if (empty($this->options['prefix']) === false) {
+			return apcu_delete(new APCUIterator('!^' . preg_quote($this->options['prefix']) . '!'));
+		}
+
+		return apcu_clear_cache();
+	}
+
+	/**
+	 * Removes an item from the cache and returns
+	 * whether the operation was successful
+	 */
+	public function remove(string $key): bool
+	{
+		return apcu_delete($this->key($key));
+	}
+
+	/**
+	 * Internal method to retrieve the raw cache value;
+	 * needs to return a Value object or null if not found
+	 */
+	public function retrieve(string $key): Value|null
+	{
+		$value = apcu_fetch($this->key($key));
+		return Value::fromJson($value);
+	}
+
+	/**
+	 * Writes an item to the cache for a given number of minutes and
+	 * returns whether the operation was successful
+	 *
+	 * ```php
+	 * // put an item in the cache for 15 minutes
+	 * $cache->set('value', 'my value', 15);
+	 * ```
+	 */
+	public function set(string $key, $value, int $minutes = 0): bool
+	{
+		$key     = $this->key($key);
+		$value   = (new Value($value, $minutes))->toJson();
+		$expires = $this->expiration($minutes);
+		return apcu_store($key, $value, $expires);
+	}
+}

kirby/src/Cache/Cache.php

@@ -0,0 +1,237 @@
+<?php
+
+namespace Kirby\Cache;
+
+use Closure;
+
+/**
+ * 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
+	 */
+	protected array $options = [];
+
+	/**
+	 * Sets all parameters which are needed to connect to the cache storage
+	 */
+	public function __construct(array $options = [])
+	{
+		$this->options = $options;
+	}
+
+	/**
+	 * Checks when the cache has been created;
+	 * returns the creation timestamp on success
+	 * and false if the item does not exist
+	 */
+	public function created(string $key): int|false
+	{
+		// get the Value object
+		$value = $this->retrieve($key);
+
+		// check for a valid Value object
+		if ($value instanceof Value === false) {
+			return false;
+		}
+
+		// return the expires timestamp
+		return $value->created();
+	}
+
+	/**
+	 * Returns whether the cache is ready to
+	 * store values
+	 */
+	public function enabled(): bool
+	{
+		// TODO: Make this method abstract in a future
+		// release to ensure that cache drivers override it;
+		// until then, we assume that the cache is enabled
+		return true;
+	}
+
+	/**
+	 * Determines if an item exists in the cache
+	 */
+	public function exists(string $key): bool
+	{
+		return $this->expired($key) === false;
+	}
+
+	/**
+	 * Calculates the expiration timestamp
+	 */
+	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
+	 */
+	public function expires(string $key): int|false|null
+	{
+		// get the Value object
+		$value = $this->retrieve($key);
+
+		// check for a valid Value object
+		if ($value instanceof Value === false) {
+			return false;
+		}
+
+		// return the expires timestamp
+		return $value->expires();
+	}
+
+	/**
+	 * Checks if an item in the cache is expired
+	 */
+	public function expired(string $key): bool
+	{
+		$expires = $this->expires($key);
+
+		if ($expires === null) {
+			return false;
+		}
+
+		if (is_int($expires) === false) {
+			return true;
+		}
+
+		return time() >= $expires;
+	}
+
+	/**
+	 * Flushes the entire cache and returns
+	 * whether the operation was successful;
+	 * this needs to be defined by the driver
+	 */
+	abstract public function flush(): bool;
+
+	/**
+	 * Gets an item from the cache
+	 *
+	 * ```php
+	 * // 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');
+	 * ```
+	 */
+	public function get(string $key, $default = null)
+	{
+		// get the Value
+		$value = $this->retrieve($key);
+
+		// check for a valid cache value
+		if ($value instanceof Value === false) {
+			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();
+	}
+
+	/**
+	 * Returns a value by either getting it from the cache
+	 * or via the callback function which then is stored in
+	 * the cache for future retrieval. This method cannot be
+	 * used for `null` as value to be cached.
+	 * @since 3.8.0
+	 */
+	public function getOrSet(
+		string $key,
+		Closure $result,
+		int $minutes = 0
+	) {
+		$value  = $this->get($key);
+		$result = $value ?? $result();
+
+		if ($value === null) {
+			$this->set($key, $result, $minutes);
+		}
+
+		return $result;
+	}
+
+	/**
+	 * Adds the prefix to the key if given
+	 */
+	protected function key(string $key): string
+	{
+		if (empty($this->options['prefix']) === false) {
+			$key = $this->options['prefix'] . '/' . $key;
+		}
+
+		return $key;
+	}
+
+	/**
+	 * Alternate version for Cache::created($key)
+	 */
+	public function modified(string $key): int|false
+	{
+		return static::created($key);
+	}
+
+	/**
+	 * Returns all passed cache options
+	 */
+	public function options(): array
+	{
+		return $this->options;
+	}
+
+	/**
+	 * Removes an item from the cache and returns
+	 * whether the operation was successful;
+	 * this needs to be defined by the driver
+	 */
+	abstract public function remove(string $key): bool;
+
+	/**
+	 * 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
+	 */
+	abstract public function retrieve(string $key): Value|null;
+
+	/**
+	 * 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
+	 *
+	 * ```php
+	 * // put an item in the cache for 15 minutes
+	 * $cache->set('value', 'my value', 15);
+	 * ```
+	 */
+	abstract public function set(string $key, $value, int $minutes = 0): bool;
+}

kirby/src/Cache/FileCache.php

@@ -0,0 +1,226 @@
+<?php
+
+namespace Kirby\Cache;
+
+use Kirby\Exception\Exception;
+use Kirby\Filesystem\Dir;
+use Kirby\Filesystem\F;
+use Kirby\Toolkit\Str;
+
+/**
+ * File System Cache Driver
+ *
+ * @package   Kirby Cache
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class FileCache extends Cache
+{
+	/**
+	 * Full root including prefix
+	 */
+	protected string $root;
+
+	/**
+	 * Sets all parameters which are needed for the file cache
+	 *
+	 * @param array $options 'root' (required)
+	 *                       'prefix' (default: none)
+	 *                       'extension' (file extension for cache files, default: none)
+	 */
+	public function __construct(array $options)
+	{
+		parent::__construct([
+			'root'      => null,
+			'prefix'    => null,
+			'extension' => null,
+			...$options
+		]);
+
+		// build the full root including prefix
+		$this->root = $this->options['root'];
+
+		if (empty($this->options['prefix']) === false) {
+			$this->root .= '/' . $this->options['prefix'];
+		}
+
+		// try to create the directory
+		Dir::make($this->root, true);
+	}
+
+	/**
+	 * Returns whether the cache is ready to
+	 * store values
+	 */
+	public function enabled(): bool
+	{
+		return is_writable($this->root) === true;
+	}
+
+	/**
+	 * Returns the full root including prefix
+	 */
+	public function root(): string
+	{
+		return $this->root;
+	}
+
+	/**
+	 * Returns the full path to a file for a given key
+	 */
+	protected function file(string $key): string
+	{
+		// strip out invalid characters in each path segment
+		// split by slash or backslash
+		$keyParts = [];
+		foreach (preg_split('#([\/\\\\])#', $key, 0, PREG_SPLIT_DELIM_CAPTURE) as $part) {
+			switch ($part) {
+				case '/':
+					// forward slashes don't need special treatment
+					break;
+
+				case '\\':
+					// backslashes get their own marker in the path
+					// to differentiate the cache key from one with forward slashes
+					$keyParts[] = '_backslash';
+					break;
+
+				case '':
+					// empty part means two slashes in a row;
+					// special marker like for backslashes
+					$keyParts[] = '_empty';
+					break;
+
+				default:
+					// an actual path segment:
+					// check if the segment only contains safe characters;
+					// underscores are *not* safe to guarantee uniqueness
+					// as they are used in the special cases
+					if (preg_match('/^[a-zA-Z0-9-]+$/', $part) === 1) {
+						$keyParts[] = $part;
+					} else {
+						$keyParts[] = Str::slug($part) . '_' . sha1($part);
+					}
+			}
+		}
+
+		$file = $this->root . '/' . implode('/', $keyParts);
+
+		if (isset($this->options['extension'])) {
+			return $file . '.' . $this->options['extension'];
+		}
+
+		return $file;
+	}
+
+	/**
+	 * Writes an item to the cache for a given number of minutes and
+	 * returns whether the operation was successful
+	 *
+	 * ```php
+	 * // put an item in the cache for 15 minutes
+	 * $cache->set('value', 'my value', 15);
+	 * ```
+	 */
+	public function set(string $key, $value, int $minutes = 0): bool
+	{
+		$file = $this->file($key);
+
+		return F::write($file, (new Value($value, $minutes))->toJson());
+	}
+
+	/**
+	 * Internal method to retrieve the raw cache value;
+	 * needs to return a Value object or null if not found
+	 */
+	public function retrieve(string $key): Value|null
+	{
+		$file  = $this->file($key);
+		$value = F::read($file);
+
+		return $value ? Value::fromJson($value) : null;
+	}
+
+	/**
+	 * Checks when the cache has been created;
+	 * returns the creation timestamp on success
+	 * and false if the item does not exist
+	 */
+	public function created(string $key): int|false
+	{
+		// use the modification timestamp
+		// as indicator when the cache has been created/overwritten
+		clearstatcache();
+
+		// get the file for this cache key
+		$file = $this->file($key);
+		return file_exists($file) ? filemtime($file) : false;
+	}
+
+	/**
+	 * Removes an item from the cache and returns
+	 * whether the operation was successful
+	 */
+	public function remove(string $key): bool
+	{
+		$file = $this->file($key);
+
+		if (is_file($file) === true && F::remove($file) === true) {
+			$this->removeEmptyDirectories(dirname($file));
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Removes empty directories safely by checking each directory
+	 * up to the root directory
+	 */
+	protected function removeEmptyDirectories(string $dir): void
+	{
+		try {
+			// ensure the path doesn't end with a slash for the next comparison
+			$dir = rtrim($dir, '/\/');
+
+			// checks all directory segments until reaching the root directory
+			while (Str::startsWith($dir, $this->root()) === true && $dir !== $this->root()) {
+				$files = scandir($dir);
+
+				if ($files === false) {
+					$files = []; // @codeCoverageIgnore
+				}
+
+				$files = array_diff($files, ['.', '..']);
+
+				if ($files === [] && Dir::remove($dir) === true) {
+					// continue with the next level up
+					$dir = dirname($dir);
+				} else {
+					// no need to continue with the next level up as `$dir` was not deleted
+					break;
+				}
+			}
+		} catch (Exception) { // @codeCoverageIgnore
+			// silently stops the process
+		}
+	}
+
+	/**
+	 * Flushes the entire cache and returns
+	 * whether the operation was successful
+	 */
+	public function flush(): bool
+	{
+		if (
+			Dir::remove($this->root) === true &&
+			Dir::make($this->root) === true
+		) {
+			return true;
+		}
+
+		return false; // @codeCoverageIgnore
+	}
+}

kirby/src/Cache/MemCached.php

@@ -0,0 +1,105 @@
+<?php
+
+namespace Kirby\Cache;
+
+use Memcached as MemcachedExt;
+
+/**
+ * Memcached Driver
+ *
+ * @package   Kirby Cache
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class MemCached extends Cache
+{
+	/**
+	 * Store for the memcache connection
+	 */
+	protected MemcachedExt $connection;
+
+	/**
+	 * Stores whether the connection was successful
+	 */
+	protected bool $enabled;
+
+	/**
+	 * Sets all parameters which are needed to connect to Memcached
+	 *
+	 * @param array $options 'host'   (default: localhost)
+	 *                       'port'   (default: 11211)
+	 *                       'prefix' (default: null)
+	 */
+	public function __construct(array $options = [])
+	{
+		parent::__construct([
+			'host'    => 'localhost',
+			'port'    => 11211,
+			'prefix'  => null,
+			...$options
+		]);
+
+		$this->connection = new MemcachedExt();
+		$this->enabled = $this->connection->addServer(
+			$this->options['host'],
+			$this->options['port']
+		);
+	}
+
+	/**
+	 * Returns whether the cache is ready to
+	 * store values
+	 */
+	public function enabled(): bool
+	{
+		return $this->enabled;
+	}
+
+	/**
+	 * Writes an item to the cache for a given number of minutes and
+	 * returns whether the operation was successful
+	 *
+	 * ```php
+	 * // put an item in the cache for 15 minutes
+	 * $cache->set('value', 'my value', 15);
+	 * ```
+	 */
+	public function set(string $key, $value, int $minutes = 0): bool
+	{
+		$key     = $this->key($key);
+		$value   = (new Value($value, $minutes))->toJson();
+		$expires = $this->expiration($minutes);
+		return $this->connection->set($key, $value, $expires);
+	}
+
+	/**
+	 * Internal method to retrieve the raw cache value;
+	 * needs to return a Value object or null if not found
+	 */
+	public function retrieve(string $key): Value|null
+	{
+		$value = $this->connection->get($this->key($key));
+		return Value::fromJson($value);
+	}
+
+	/**
+	 * Removes an item from the cache and returns
+	 * whether the operation was successful
+	 */
+	public function remove(string $key): bool
+	{
+		return $this->connection->delete($this->key($key));
+	}
+
+	/**
+	 * Flushes the entire cache and returns
+	 * whether the operation was successful;
+	 * WARNING: Memcached only supports flushing the whole cache at once!
+	 */
+	public function flush(): bool
+	{
+		return $this->connection->flush();
+	}
+}

kirby/src/Cache/MemoryCache.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace Kirby\Cache;
+
+/**
+ * Memory Cache Driver (cache in memory for current request only)
+ *
+ * @package   Kirby Cache
+ * @author    Lukas Bestle <lukas@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class MemoryCache extends Cache
+{
+	/**
+	 * Cache data
+	 */
+	protected array $store = [];
+
+	/**
+	 * Returns whether the cache is ready to
+	 * store values
+	 */
+	public function enabled(): bool
+	{
+		return true;
+	}
+
+	/**
+	 * Writes an item to the cache for a given number of minutes and
+	 * returns whether the operation was successful
+	 *
+	 * ```php
+	 * // put an item in the cache for 15 minutes
+	 * $cache->set('value', 'my value', 15);
+	 * ```
+	 */
+	public function set(string $key, $value, int $minutes = 0): bool
+	{
+		$this->store[$key] = new Value($value, $minutes);
+		return true;
+	}
+
+	/**
+	 * Internal method to retrieve the raw cache value;
+	 * needs to return a Value object or null if not found
+	 */
+	public function retrieve(string $key): Value|null
+	{
+		return $this->store[$key] ?? null;
+	}
+
+	/**
+	 * Removes an item from the cache and returns
+	 * whether the operation was successful
+	 */
+	public function remove(string $key): bool
+	{
+		if (isset($this->store[$key])) {
+			unset($this->store[$key]);
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Flushes the entire cache and returns
+	 * whether the operation was successful
+	 */
+	public function flush(): bool
+	{
+		$this->store = [];
+		return true;
+	}
+}

kirby/src/Cache/NullCache.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace Kirby\Cache;
+
+/**
+ * Dummy Cache Driver (does not do any caching)
+ *
+ * @package   Kirby Cache
+ * @author    Lukas Bestle <lukas@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class NullCache extends Cache
+{
+	/**
+	 * Returns whether the cache is ready to
+	 * store values
+	 */
+	public function enabled(): bool
+	{
+		return false;
+	}
+
+	/**
+	 * Writes an item to the cache for a given number of minutes and
+	 * returns whether the operation was successful
+	 *
+	 * ```php
+	 * // put an item in the cache for 15 minutes
+	 * $cache->set('value', 'my value', 15);
+	 * ```
+	 */
+	public function set(string $key, $value, int $minutes = 0): bool
+	{
+		return true;
+	}
+
+	/**
+	 * Internal method to retrieve the raw cache value;
+	 * needs to return a Value object or null if not found
+	 */
+	public function retrieve(string $key): Value|null
+	{
+		return null;
+	}
+
+	/**
+	 * Removes an item from the cache and returns
+	 * whether the operation was successful
+	 */
+	public function remove(string $key): bool
+	{
+		return true;
+	}
+
+	/**
+	 * Flushes the entire cache and returns
+	 * whether the operation was successful
+	 */
+	public function flush(): bool
+	{
+		return true;
+	}
+}

kirby/src/Cache/RedisCache.php

@@ -0,0 +1,160 @@
+<?php
+
+namespace Kirby\Cache;
+
+use Kirby\Cms\Helpers;
+use Redis;
+use Throwable;
+
+/**
+ * Redis Cache Driver
+ *
+ * @package   Kirby Cache
+ * @author    Ahmet Bora <ahmet@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class RedisCache extends Cache
+{
+	/**
+	 * Store for the redis connection
+	 */
+	protected Redis $connection;
+
+	/**
+	 * Sets all parameters which are needed to connect to Redis
+	 *
+	 * @param array $options 'host'   (default: 127.0.0.1)
+	 *                       'port'   (default: 6379)
+	 */
+	public function __construct(array $options = [])
+	{
+		$options = [
+			'host' => '127.0.0.1',
+			'port' => 6379,
+			...$options
+		];
+
+		parent::__construct($options);
+
+		// available options for the redis driver
+		$allowed = [
+			'host',
+			'port',
+			'readTimeout',
+			'connectTimeout',
+			'persistent',
+			'auth',
+			'ssl',
+			'retryInterval',
+			'backoff'
+		];
+
+		// filters only redis supported keys
+		$redisOptions = array_intersect_key($options, array_flip($allowed));
+
+		// creates redis connection
+		$this->connection = new Redis($redisOptions);
+
+		// sets the prefix if defined
+		if ($prefix = $options['prefix'] ?? null) {
+			$this->connection->setOption(Redis::OPT_PREFIX, rtrim($prefix, '/') . '/');
+		}
+
+		// selects the database if defined
+		$database = $options['database'] ?? null;
+		if ($database !== null) {
+			$this->connection->select($database);
+		}
+	}
+
+	/**
+	 * Returns the database number
+	 */
+	public function databaseNum(): int
+	{
+		return $this->connection->getDbNum();
+	}
+
+	/**
+	 * Returns whether the cache is ready to store values
+	 */
+	public function enabled(): bool
+	{
+		try {
+			return Helpers::handleErrors(
+				fn () => $this->connection->ping(),
+				fn (int $errno, string $errstr) => true,
+				fn () => false
+			);
+		} catch (Throwable) {
+			return false;
+		}
+	}
+
+	/**
+	 * Determines if an item exists in the cache
+	 */
+	public function exists(string $key): bool
+	{
+		return $this->connection->exists($this->key($key)) !== 0;
+	}
+
+	/**
+	 * Removes keys from the database
+	 * and returns whether the operation was successful
+	 */
+	public function flush(): bool
+	{
+		return $this->connection->flushDB();
+	}
+
+	/**
+	 * The key is not modified, because the prefix is added by the redis driver itself
+	 */
+	protected function key(string $key): string
+	{
+		return $key;
+	}
+
+	/**
+	 * Removes an item from the cache
+	 * and returns whether the operation was successful
+	 */
+	public function remove(string $key): bool
+	{
+		return $this->connection->del($this->key($key));
+	}
+
+	/**
+	 * Internal method to retrieve the raw cache value;
+	 * needs to return a Value object or null if not found
+	 */
+	public function retrieve(string $key): Value|null
+	{
+		$value = $this->connection->get($this->key($key));
+		return Value::fromJson($value);
+	}
+
+	/**
+	 * Writes an item to the cache for a given number of minutes
+	 * and returns whether the operation was successful
+	 *
+	 * ```php
+	 * // put an item in the cache for 15 minutes
+	 * $cache->set('value', 'my value', 15);
+	 * ```
+	 */
+	public function set(string $key, $value, int $minutes = 0): bool
+	{
+		$key   = $this->key($key);
+		$value = (new Value($value, $minutes))->toJson();
+
+		if ($minutes > 0) {
+			return $this->connection->setex($key, $minutes * 60, $value);
+		}
+
+		return $this->connection->set($key, $value);
+	}
+}

kirby/src/Cache/Value.php

@@ -0,0 +1,137 @@
+<?php
+
+namespace Kirby\Cache;
+
+use Throwable;
+
+/**
+ * Cache Value
+ * Stores the value, creation timestamp and expiration timestamp
+ * and makes it possible to store all three with a single cache key
+ *
+ * @package   Kirby Cache
+ * @author    Bastian Allgeier <bastian@getkirby.com>
+ * @link      https://getkirby.com
+ * @copyright Bastian Allgeier
+ * @license   https://opensource.org/licenses/MIT
+ */
+class Value
+{
+	/**
+	 * Cached value
+	 */
+	protected mixed $value;
+
+	/**
+	 * the number of minutes until the value expires
+	 * @todo Rename this property to $expiry to reflect
+	 *       both minutes and absolute timestamps
+	 */
+	protected int $minutes;
+
+	/**
+	 * Creation timestamp
+	 */
+	protected int $created;
+
+	/**
+	 * Constructor
+	 *
+	 * @param int $minutes the number of minutes until the value expires
+	 *                     or an absolute UNIX timestamp
+	 * @param int|null $created the UNIX timestamp when the value has been created
+	 *                          (defaults to the current time)
+	 */
+	public function __construct($value, int $minutes = 0, int|null $created = null)
+	{
+		$this->value   = $value;
+		$this->minutes = $minutes;
+		$this->created = $created ?? time();
+	}
+
+	/**
+	 * Returns the creation date as UNIX timestamp
+	 */
+	public function created(): int
+	{
+		return $this->created;
+	}
+
+	/**
+	 * Returns the expiration date as UNIX timestamp or
+	 * null if the value never expires
+	 */
+	public function expires(): int|null
+	{
+		// 0 = keep forever
+		if ($this->minutes === 0) {
+			return null;
+		}
+
+		if ($this->minutes > 1000000000) {
+			// absolute timestamp
+			return $this->minutes;
+		}
+
+		return $this->created + ($this->minutes * 60);
+	}
+
+	/**
+	 * Creates a value object from an array
+	 */
+	public static function fromArray(array $array): static
+	{
+		return new static(
+			$array['value'] ?? null,
+			$array['minutes'] ?? 0,
+			$array['created'] ?? null
+		);
+	}
+
+	/**
+	 * Creates a value object from a JSON string;
+	 * returns null on error
+	 */
+	public static function fromJson(string $json): static|null
+	{
+		try {
+			$array = json_decode($json, true);
+
+			if (is_array($array) === true) {
+				return static::fromArray($array);
+			}
+
+			return null;
+		} catch (Throwable) {
+			return null;
+		}
+	}
+
+	/**
+	 * Converts the object to a JSON string
+	 */
+	public function toJson(): string
+	{
+		return json_encode($this->toArray());
+	}
+
+	/**
+	 * Converts the object to an array
+	 */
+	public function toArray(): array
+	{
+		return [
+			'created' => $this->created,
+			'minutes' => $this->minutes,
+			'value'   => $this->value,
+		];
+	}
+
+	/**
+	 * Returns the pure value
+	 */
+	public function value()
+	{
+		return $this->value;
+	}
+}