feat(cache): separate internal and user caches

.env.example

@@ -4,25 +4,12 @@ ENVIRONMENT=local
 # The base URI that's used for all generated URIs
 BASE_URI=http://localhost
 
-# The CACHE key is used as a global override to turn all caches on or off
-# Should be true in production, but null or false in local development
-CACHE=null
+# Setting to `false` force-disable internal caches.
+INTERNAL_CACHES=true
 
-# Enable or disable discovery cache
+# Enable or disable discovery cache. Can be `true`, `partial` or `false`.
 DISCOVERY_CACHE=false
 
-# Enable or disable config cache
-CONFIG_CACHE=false
-
-# Enable or disable icon cache
-ICON_CACHE=true
-
-# Enable or disable view cache
-VIEW_CACHE=false
-
-# Enable or disable project cache (allround cache)
-PROJECT_CACHE=false
-
 # Overwrite default log paths (null = default)
 DEBUG_LOG_PATH=null
-SERVER_LOG_PATH=null
+SERVER_LOG_PATH=null

packages/cache/src/Cache.php

@@ -6,20 +6,88 @@
 
 use Closure;
 use Psr\Cache\CacheItemInterface;
+use Stringable;
 use Tempest\DateTime\DateTimeInterface;
+use Tempest\DateTime\Duration;
 
 interface Cache
 {
-    public function put(string $key, mixed $value, ?DateTimeInterface $expiresAt = null): CacheItemInterface;
+    /**
+     * Whether the cache is enabled.
+     */
+    public bool $enabled {
+        get;
+        set;
+    }
 
-    public function get(string $key): mixed;
+    /**
+     * Returns a lock for the specified key. The lock is not acquired until `acquire()` is called.
+     *
+     * @param Stringable|string $key The identifier of the lock.
+     * @param null|Duration|DateTimeInterface $expiration The expiration time for the lock. If not specified, the lock will not expire.
+     * @param null|Stringable|string $owner The owner of the lock, which will be used to identify the process releasing it. If not specified, a random string will be used.
+     */
+    public function lock(Stringable|string $key, null|Duration|DateTimeInterface $expiration = null, null|Stringable|string $owner = null): Lock;
 
-    /** @param Closure(): mixed $cache */
-    public function resolve(string $key, Closure $cache, ?DateTimeInterface $expiresAt = null): mixed;
+    /**
+     * Sets the specified key to the specified value in the cache. Optionally, specify an expiration.
+     */
+    public function put(Stringable|string $key, mixed $value, null|Duration|DateTimeInterface $expiration = null): CacheItemInterface;
 
-    public function remove(string $key): void;
+    /**
+     * Sets the specified keys to the specified values in the cache. Optionally, specify an expiration.
+     *
+     * @template TKey of array-key
+     * @template TValue
+     *
+     * @param iterable<TKey,TValue> $array
+     * @return array<TKey,CacheItemInterface>
+     */
+    public function putMany(iterable $values, null|Duration|DateTimeInterface $expiration = null): array;
 
-    public function clear(): void;
+    /**
+     * Gets the value associated with the specified key from the cache. If the key does not exist, null is returned.
+     */
+    public function get(Stringable|string $key): mixed;
+
+    /**
+     * Gets the values associated with the specified keys from the cache. If a key does not exist, null is returned for that key.
+     *
+     * @template TKey of array-key
+     * @template TValue
+     *
+     * @param iterable<TKey,TValue> $array
+     * @return array<TValue,mixed>
+     */
+    public function getMany(iterable $key): array;
+
+    /**
+     * Determines whether the cache contains the specified key.
+     */
+    public function has(Stringable|string $key): bool;
+
+    /**
+     * Increments the value associated with the specified key by the specified amount. If the key does not exist, it is created with the specified amount.
+     */
+    public function increment(Stringable|string $key, int $by = 1): int;
 
-    public function isEnabled(): bool;
+    /**
+     * Decrements the value associated with the specified key by the specified amount. If the key does not exist, it is created with the negative amount.
+     */
+    public function decrement(Stringable|string $key, int $by = 1): int;
+
+    /**
+     * If the specified key already exists in the cache, the value is returned and the `$callback` is not executed. Otherwise, the result of the callback is stored, then returned.
+     */
+    public function resolve(Stringable|string $key, Closure $callback, null|Duration|DateTimeInterface $expiration = null): mixed;
+
+    /**
+     * Removes the specified key from the cache.
+     */
+    public function remove(Stringable|string $key): void;
+
+    /**
+     * Clears the entire cache.
+     */
+    public function clear(): void;
 }

packages/cache/src/CacheException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace Tempest\Cache;
+
+interface CacheException
+{
+}

packages/cache/src/CacheInitializer.php

@@ -4,15 +4,46 @@
 
 namespace Tempest\Cache;
 
+use Tempest\Cache\Config\CacheConfig;
 use Tempest\Container\Container;
-use Tempest\Container\Initializer;
+use Tempest\Container\DynamicInitializer;
 use Tempest\Container\Singleton;
+use Tempest\Reflection\ClassReflector;
 
-final readonly class CacheInitializer implements Initializer
+use function Tempest\env;
+use function Tempest\Support\str;
+
+final readonly class CacheInitializer implements DynamicInitializer
 {
+    public function canInitialize(ClassReflector $class, ?string $tag): bool
+    {
+        return $class->getType()->matches(Cache::class);
+    }
+
     #[Singleton]
-    public function initialize(Container $container): Cache|ProjectCache
+    public function initialize(ClassReflector $class, ?string $tag, Container $container): Cache
+    {
+        return new GenericCache(
+            cacheConfig: $container->get(CacheConfig::class, $tag),
+            enabled: $this->shouldCacheBeEnabled($tag),
+        );
+    }
+
+    private function shouldCacheBeEnabled(?string $tag): bool
     {
-        return new ProjectCache($container->get(CacheConfig::class));
+        $globalCacheEnabled = (bool) env('CACHE_ENABLED', default: true);
+
+        if (! $tag) {
+            return $globalCacheEnabled;
+        }
+
+        $environmentVariableName = str($tag)
+            ->snake()
+            ->upper()
+            ->prepend('CACHE_')
+            ->append('_ENABLED')
+            ->toString();
+
+        return (bool) env($environmentVariableName, default: $globalCacheEnabled);
     }
 }