* @copyright 2026 Nowo.tech */ class PerformanceCacheService { /** * Cache key prefix for performance bundle cache items. */ private const CACHE_PREFIX = 'nowo_performance_'; /** * Default TTL for cache items (1 hour). */ private const DEFAULT_TTL = 3600; /** * Cache pool instance. */ private readonly ?CacheItemPoolInterface $cachePool; /** * Creates a new instance. * * @param CacheItemPoolInterface|string|null $cachePool The cache pool (optional; bundle configures nowo_performance.cache by default) */ public function __construct( CacheItemPoolInterface|string|null $cachePool = null, ) { // Handle case where cache service might not be available (string passed instead of null) // or when the service is not configured $this->cachePool = $cachePool instanceof CacheItemPoolInterface ? $cachePool : null; } /** * Get cached statistics for an environment. * * @param string $env The environment * * @return array|null Cached statistics or null if not cached */ public function getCachedStatistics(string $env): ?array { if (!$this->cachePool instanceof CacheItemPoolInterface) { return null; } $key = $this->getStatisticsKey($env); $item = $this->cachePool->getItem($key); if ($item->isHit()) { return $item->get(); } return null; } /** * Cache statistics for an environment. * * @param string $env The environment * @param array $statistics The statistics to cache * @param int|null $ttl Time to live in seconds (default: 1 hour) * * @return bool True if cached successfully */ public function cacheStatistics(string $env, array $statistics, ?int $ttl = null): bool { if (!$this->cachePool instanceof CacheItemPoolInterface) { return false; } $key = $this->getStatisticsKey($env); $item = $this->cachePool->getItem($key); $item->set($statistics); $item->expiresAfter($ttl ?? self::DEFAULT_TTL); return $this->cachePool->save($item); } /** * Get cached environment list. * * @return string[]|null Cached environment list or null if not cached */ public function getCachedEnvironments(): ?array { if (!$this->cachePool instanceof CacheItemPoolInterface) { return null; } $key = $this->getEnvironmentsKey(); $item = $this->cachePool->getItem($key); if ($item->isHit()) { return $item->get(); } return null; } /** * Cache environment list. * * @param string[] $environments The environment list to cache * @param int|null $ttl Time to live in seconds (default: 1 hour) * * @return bool True if cached successfully */ public function cacheEnvironments(array $environments, ?int $ttl = null): bool { if (!$this->cachePool instanceof CacheItemPoolInterface) { return false; } $key = $this->getEnvironmentsKey(); $item = $this->cachePool->getItem($key); $item->set($environments); $item->expiresAfter($ttl ?? self::DEFAULT_TTL); return $this->cachePool->save($item); } /** * Invalidate statistics cache for an environment. * * Bumps a generation counter so new reads use a fresh cache key instead of * deleting items synchronously on every write. * * @param string $env The environment * * @return bool True if invalidated successfully */ public function invalidateStatistics(string $env): bool { if (!$this->cachePool instanceof CacheItemPoolInterface) { return false; } $key = $this->getStatisticsGenerationKey($env); $item = $this->cachePool->getItem($key); $gen = $item->isHit() ? (int) $item->get() : 0; $item->set($gen + 1); $item->expiresAfter(self::DEFAULT_TTL); return $this->cachePool->save($item); } /** * Invalidate environment list cache. * * @return bool True if invalidated successfully */ public function invalidateEnvironments(): bool { if (!$this->cachePool instanceof CacheItemPoolInterface) { return false; } $key = $this->getEnvironmentsKey(); return $this->cachePool->deleteItem($key); } /** * Invalidate all performance cache. * * @return bool True if invalidated successfully */ public function invalidateAll(): bool { if (!$this->cachePool instanceof CacheItemPoolInterface) { return false; } // Invalidate environments cache (statistics will be invalidated on next update) return $this->invalidateEnvironments(); } /** * Clear statistics cache for an environment. * * Alias for invalidateStatistics(). * * @param string $env The environment * * @return bool True if cleared successfully */ public function clearStatistics(string $env): bool { return $this->invalidateStatistics($env); } /** * Clear environment list cache. * * Alias for invalidateEnvironments(). * * @return bool True if cleared successfully */ public function clearEnvironments(): bool { return $this->invalidateEnvironments(); } /** * Get cache key for statistics. * * @param string $env The environment * * @return string The cache key */ private function getStatisticsKey(string $env): string { return self::CACHE_PREFIX . 'stats_' . $env . '_v' . $this->getStatisticsGeneration($env); } /** * Get cache key for statistics generation counter. */ private function getStatisticsGenerationKey(string $env): string { return self::CACHE_PREFIX . 'stats_gen_' . $env; } /** * Read the current statistics cache generation for an environment. */ private function getStatisticsGeneration(string $env): int { // Callers return early without a pool; the throw documents the invariant (no unreachable `return 0` branch). $pool = $this->cachePool ?? throw new LogicException('The statistics cache generation needs a cache pool.'); $item = $pool->getItem($this->getStatisticsGenerationKey($env)); if ($item->isHit()) { return (int) $item->get(); } return 0; } /** * Get cache key for environments list. * * @return string The cache key */ private function getEnvironmentsKey(): string { return self::CACHE_PREFIX . 'environments'; } /** * Get a cached value by key. * * @param string $key The cache key * * @return mixed|null The cached value or null if not found */ public function getCachedValue(string $key): mixed { if (!$this->cachePool instanceof CacheItemPoolInterface) { return null; } $item = $this->cachePool->getItem(self::CACHE_PREFIX . $key); if ($item->isHit()) { return $item->get(); } return null; } /** * Cache a value by key. * * @param string $key The cache key * @param mixed $value The value to cache * @param int|null $ttl Time to live in seconds (default: 1 hour) * * @return bool True if cached successfully */ public function cacheValue(string $key, mixed $value, ?int $ttl = null): bool { if (!$this->cachePool instanceof CacheItemPoolInterface) { return false; } $item = $this->cachePool->getItem(self::CACHE_PREFIX . $key); $item->set($value); $item->expiresAfter($ttl ?? self::DEFAULT_TTL); return $this->cachePool->save($item); } /** * Invalidate a cached value by key. * * @param string $key The cache key * * @return bool True if invalidated successfully */ public function invalidateValue(string $key): bool { if (!$this->cachePool instanceof CacheItemPoolInterface) { return false; } return $this->cachePool->deleteItem(self::CACHE_PREFIX . $key); } }