refactor(core): harden runtime cache service

Author: ImperaZim

CHANGELOG.md

@@ -354,6 +354,10 @@ elprobe run <package>
   Config wrapper; pass a directory string or use PocketMine `Config` directly.
 - `File`, `Path`, `FileExtensionTypes` and `FileSystemException` remain part of
   the core filesystem direction and will be hardened rather than removed.
+- `PluginToolkit`, `PluginComponent` and their toolkit traits remain part of
+  the core plugin/component direction and will be hardened rather than removed.
+- `Cache` is now documented and hardened as a small runtime-only core service:
+  local memory, TTL support, no persistence and no distributed state.
 - Component enable/disable notices now use PocketMine `TextFormat` constants
   instead of raw section-sign color codes in the core component logger.
 

README.md

@@ -25,7 +25,9 @@ The 3.x direction is: EasyLibrary becomes the minimal manager, official libs bec
 - A plugin-owned module system with manifests, dependency checks, lifecycle cleanup, services and capabilities.
 - Core infrastructure components for the package manager, plugin toolkit,
   filesystem helpers, Config Split support and the small runtime cache
-  component.
+  component. The cache is runtime-only memory, not persistent storage.
+- `PluginToolkit`/`PluginComponent` and `File`/`Path` are kept as long-term
+  EasyLibrary core directions; they may be refined or moved, not removed.
 - Optional Agent Bridge support for network-aware plugins that need PubSub, registry, KV, flags, locks, RPC, runtime events or safe compute services.
 
 ## Requirements

changelogs/3.0.md

@@ -1545,6 +1545,10 @@ Reload rereads config files for future EasyLibrary operations. It does not:
   use PocketMine `Config` directly for normal config files.
 - `File`, `Path`, `FileExtensionTypes` and `FileSystemException` remain part of
   the core filesystem direction and will be hardened rather than removed.
+- `PluginToolkit`, `PluginComponent` and their toolkit traits remain part of
+  the core plugin/component direction and will be hardened rather than removed.
+- `Cache` is now treated as a small runtime-only core service: local memory,
+  TTL support, no persistence and no distributed state.
 - Component enable/disable notices now use PocketMine `TextFormat` constants
   instead of raw section-sign color codes in `LibraryComponents`.
 
@@ -1596,6 +1600,17 @@ The filesystem area is different: `File` and `Path` are actively useful to the
 core and remain part of the EasyLibrary direction. They may be renamed, moved or
 hardened, but the idea should stay available.
 
+The plugin toolkit area follows the same rule. `PluginToolkit`,
+`PluginComponent`, `PluginToolkitTrait`, `PluginComponentsTrait`,
+`ComponentTypesTrait` and `PluginException` may be renamed, moved or hardened,
+but the toolkit/component idea should stay available.
+
+The cache area is also kept, but intentionally small. It is useful as a local
+runtime helper for the core and compatibility components, but it should not grow
+into persistent storage, distributed cache or an adapter framework inside the
+EasyLibrary core. If that need appears later, it should be extracted into a
+focused package.
+
 The component logging polish is intentionally small but useful for the 3.x
 cleanup: active core output should be generated through PocketMine formatting
 APIs instead of embedded formatting bytes. This keeps console output and future

src/imperazim/components/cache/Cache.php

@@ -9,20 +9,25 @@
 use imperazim\components\plugin\traits\PluginComponentsTrait;
 
 /**
-* Class Cache
-* @package imperazim\components\cache
+* Runtime-only in-memory cache used by EasyLibrary and compatibility components.
+*
+* This cache is intentionally small: it does not persist data, does not provide
+* distributed state and should not grow into a storage framework.
+*
+* @phpstan-type CacheEntry array{value: mixed, expires_at: int|null}
 */
 final class Cache extends PluginComponent {
   use PluginComponentsTrait;
 
   /**
-  * @var array An associative array where keys represent cache keys and values represent cached data with expiration.
+  * @var array<string, CacheEntry>
   */
   private static array $cache = [];
 
   /**
-  * Initializes the Cache component.
-  * @param PluginToolkit $plugin The Plugin.
+  * Initializes the runtime cache component.
+  *
+  * @return array<string, mixed>
   */
   public static function init(PluginToolkit $plugin): array {
     return [];
@@ -44,45 +49,35 @@ public static function close(PluginToolkit $plugin): void {
   public static function put(string $key, mixed $value, ?int $ttl = null): void {
     self::$cache[$key] = [
       'value' => $value,
-      'expires_at' => $ttl !== null ? time() + $ttl : null
+      'expires_at' => $ttl !== null ? self::now() + max(0, $ttl) : null
     ];
   }
 
   /**
-  * Retrieves cached data by key, returning null if the data is expired or doesn't exist.
-  * @param string $key The cache key.
-  * @return mixed|null The cached value or null if expired/not found.
+  * Retrieves cached data by key, returning null if the entry is expired or missing.
   */
   public static function get(string $key): mixed {
-    if (!isset(self::$cache[$key])) {
+    if (!array_key_exists($key, self::$cache)) {
       return null;
     }
 
-    $cacheItem = self::$cache[$key];
-
-    // Check if the item has expired
-    if ($cacheItem['expires_at'] !== null && $cacheItem['expires_at'] < time()) {
+    if (self::isEntryExpired(self::$cache[$key])) {
       self::invalidate($key);
       return null;
     }
 
-    return $cacheItem['value'];
+    return self::$cache[$key]['value'];
   }
 
   /**
   * Checks if a cache key exists and is not expired.
-  * @param string $key The cache key.
-  * @return bool True if the key exists and is not expired, false otherwise.
   */
   public static function has(string $key): bool {
-    if (!isset(self::$cache[$key])) {
+    if (!array_key_exists($key, self::$cache)) {
       return false;
     }
 
-    $cacheItem = self::$cache[$key];
-
-    // Check if the item has expired
-    if ($cacheItem['expires_at'] !== null && $cacheItem['expires_at'] < time()) {
+    if (self::isEntryExpired(self::$cache[$key])) {
       self::invalidate($key);
       return false;
     }
@@ -98,9 +93,8 @@ public static function has(string $key): bool {
   * @return mixed The cached value or callback result.
   */
   public static function remember(string $key, callable $callback, ?int $ttl = null): mixed {
-    $value = self::get($key);
-    if ($value !== null) {
-      return $value;
+    if (self::has($key)) {
+      return self::get($key);
     }
 
     $value = $callback();
@@ -125,19 +119,21 @@ public static function clear(): void {
 
   /**
   * Stores multiple values in the cache with optional TTL.
-  * @param array $items Associative array of key => value pairs.
+  *
+  * @param array<int|string, mixed> $items Associative array of key => value pairs.
   * @param int|null $ttl Time to live in seconds. Null for no expiration.
   */
   public static function putMany(array $items, ?int $ttl = null): void {
     foreach ($items as $key => $value) {
-      self::put($key, $value, $ttl);
+      self::put((string) $key, $value, $ttl);
     }
   }
 
   /**
   * Retrieves multiple cached values by keys.
-  * @param array $keys Array of cache keys.
-  * @return array Associative array of key => value pairs (null for missing/expired).
+  *
+  * @param array<int, string> $keys Array of cache keys.
+  * @return array<string, mixed|null> Associative array of key => value pairs.
   */
   public static function getMany(array $keys): array {
     $results = [];
@@ -151,9 +147,9 @@ public static function getMany(array $keys): array {
   * Removes expired cache entries.
   */
   public static function purgeExpired(): void {
-    $currentTime = time();
+    $currentTime = self::now();
     foreach (self::$cache as $key => $item) {
-      if ($item['expires_at'] !== null && $item['expires_at'] < $currentTime) {
+      if (self::isEntryExpired($item, $currentTime)) {
         unset(self::$cache[$key]);
       }
     }
@@ -222,6 +218,7 @@ public static function exists(string $key): bool {
   * @return int Number of cached entries.
   */
   public static function size(): int {
+    self::purgeExpired();
     return count(self::$cache);
   }
 
@@ -231,11 +228,11 @@ public static function size(): int {
   * @return bool True if the key exists but has expired.
   */
   public static function isExpired(string $key): bool {
-    if (!isset(self::$cache[$key])) {
-      return false; // Key doesn't exist, so it's not "expired" - it never existed
+    if (!array_key_exists($key, self::$cache)) {
+      return false;
     }
-    $item = self::$cache[$key];
-    return $item['expires_at'] !== null && $item['expires_at'] < time();
+
+    return self::isEntryExpired(self::$cache[$key]);
   }
 
   /**
@@ -244,48 +241,64 @@ public static function isExpired(string $key): bool {
   * @return int|null Remaining TTL in seconds, or null if key doesn't exist or has no expiration.
   */
   public static function getRemainingTtl(string $key): ?int {
-    if (!isset(self::$cache[$key])) {
+    if (!self::has($key)) {
       return null;
     }
+
     $item = self::$cache[$key];
     if ($item['expires_at'] === null) {
-      return null; // No expiration
+      return null;
     }
-    $remaining = $item['expires_at'] - time();
-    return max(0, $remaining); // Don't return negative values
+
+    return max(0, $item['expires_at'] - self::now());
   }
 
   /**
   * Returns all cache entries as an associative array.
-  * @return array All cache entries [key => value].
+  *
+  * @return array<string, mixed> All active cache entries [key => value].
   */
   public static function all(): array {
+    self::purgeExpired();
+
     $result = [];
     foreach (self::$cache as $key => $item) {
-      if ($item['expires_at'] === null || $item['expires_at'] > time()) {
-        $result[$key] = $item['value'];
-      }
+      $result[$key] = $item['value'];
     }
     return $result;
   }
 
   /**
   * Returns cache statistics such as total entries, hits, misses, and expired items.
-  * @return array Cache statistics.
+  *
+  * @return array{total_entries: int, active_entries: int, expired_entries: int}
   */
   public static function getStats(): array {
     $totalEntries = count(self::$cache);
     $expiredEntries = 0;
+    $currentTime = self::now();
 
     foreach (self::$cache as $key => $item) {
-      if ($item['expires_at'] !== null && $item['expires_at'] < time()) {
+      if (self::isEntryExpired($item, $currentTime)) {
         $expiredEntries++;
       }
     }
 
     return [
       'total_entries' => $totalEntries,
+      'active_entries' => $totalEntries - $expiredEntries,
       'expired_entries' => $expiredEntries
     ];
   }
-}
+
+  private static function now(): int {
+    return time();
+  }
+
+  /**
+  * @param CacheEntry $entry
+  */
+  private static function isEntryExpired(array $entry, ?int $now = null): bool {
+    return $entry['expires_at'] !== null && $entry['expires_at'] <= ($now ?? self::now());
+  }
+}