From ec684e910d0a1ccc0b5859e5b4a76af86ad2fbf5 Mon Sep 17 00:00:00 2001 From: "A. B. M. Mahmudul Hasan" Date: Mon, 22 Jun 2026 13:49:46 +0600 Subject: [PATCH] fix --- .gitignore | 1 + src/Cache/Adapter/AbstractCacheAdapter.php | 56 +++--- src/Cache/Adapter/AdapterValueNormalizer.php | 14 +- src/Cache/Adapter/ApcuCacheAdapter.php | 25 ++- src/Cache/Adapter/ArrayCacheAdapter.php | 8 +- src/Cache/Adapter/CachePayloadCodec.php | 17 +- src/Cache/Adapter/ChainCacheAdapter.php | 12 +- src/Cache/Adapter/FileCacheAdapter.php | 9 +- src/Cache/Adapter/MemCacheAdapter.php | 57 +++++-- src/Cache/Adapter/MongoDbCacheAdapter.php | 8 +- src/Cache/Adapter/NullCacheAdapter.php | 8 +- src/Cache/Adapter/PdoCacheAdapter.php | 24 ++- src/Cache/Adapter/PhpFilesCacheAdapter.php | 8 +- src/Cache/Adapter/RedisCacheAdapter.php | 17 +- .../Adapter/RedisClusterCacheAdapter.php | 16 +- src/Cache/Adapter/ScyllaDbCacheAdapter.php | 36 ++-- .../Adapter/SharedMemoryCacheAdapter.php | 13 +- src/Cache/Adapter/WeakMapCacheAdapter.php | 8 +- src/Cache/Cache.php | 160 +++++++++++------- src/Cache/CacheInterface.php | 19 ++- src/Cache/CacheReadRememberTrait.php | 10 +- src/Cache/Item/AbstractCacheItem.php | 9 +- src/Cache/Item/FileCacheItem.php | 8 - src/Cache/Lock/FileLockProvider.php | 5 +- src/Cache/Lock/PollingLockProviderHelpers.php | 10 +- .../CacheMetricsCollectorInterface.php | 2 +- src/Cache/Tiering/TieredPoolFactory.php | 62 +++++-- src/Memoize/Memoizer.php | 18 +- src/Serializer/ValueSerializer.php | 45 +++-- 29 files changed, 439 insertions(+), 246 deletions(-) diff --git a/.gitignore b/.gitignore index 961285c..f02dfc8 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,4 @@ patch.php test.php var vendor +.codex diff --git a/src/Cache/Adapter/AbstractCacheAdapter.php b/src/Cache/Adapter/AbstractCacheAdapter.php index 95dae0a..1430d62 100644 --- a/src/Cache/Adapter/AbstractCacheAdapter.php +++ b/src/Cache/Adapter/AbstractCacheAdapter.php @@ -9,16 +9,6 @@ use Psr\Cache\CacheItemInterface; use Psr\Cache\CacheItemPoolInterface; -/** - * Abstract base class for cache adapter implementations. - * - * This class provides a foundation for building PSR-6 and PSR-16 compliant - * cache adapters. It implements common functionality like deferred item management - * and provides default implementations for several cache pool interface methods. - * - * Adapters extending this class must implement the abstract methods required - * for their specific storage mechanism while inheriting common cache operations. - */ abstract class AbstractCacheAdapter implements CacheItemPoolInterface, Countable, InternalCachePoolInterface { /** @var array */ @@ -28,7 +18,6 @@ abstract class AbstractCacheAdapter implements CacheItemPoolInterface, Countable * Determines if this adapter supports the given cache item. * * @param CacheItemInterface $item The cache item to check. - * @return bool True if the adapter supports this item type. */ abstract protected function supportsItem(CacheItemInterface $item): bool; @@ -51,8 +40,9 @@ public function get(string $key): mixed } /** - * @param list $keys - * @return iterable + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return iterable */ public function getItems(array $keys = []): iterable { @@ -90,7 +80,8 @@ public function set(string $key, mixed $value, ?int $ttl = null): bool } /** - * @return array{value:mixed,expires:int|null}|null + * @phpstan-return array{value:mixed,expires:int|null}|null + * @param string $payload The payload argument. */ protected function decodeRecordFromBase64(string $payload): ?array { @@ -103,7 +94,8 @@ protected function decodeRecordFromBase64(string $payload): ?array } /** - * @return array{value:mixed,expires:int|null}|null + * @phpstan-return array{value:mixed,expires:int|null}|null + * @param string $blob The blob argument. */ protected function decodeRecordFromBlob(string $blob): ?array { @@ -132,7 +124,10 @@ protected function genericFromBase64(string $key, ?string $payload): GenericCach } /** - * @param callable():bool $onInvalid + * @param string $key The key argument. + * @param string|null $payload The payload argument. + * @param callable $onInvalid The on invalid argument. + * @phpstan-param callable():bool $onInvalid */ protected function genericFromBase64WithInvalidator(string $key, ?string $payload, callable $onInvalid): GenericCacheItem { @@ -149,7 +144,10 @@ protected function genericFromBlob(string $key, ?string $blob): GenericCacheItem } /** - * @param callable():bool $onInvalid + * @param string $key The key argument. + * @param string|null $blob The blob argument. + * @param callable $onInvalid The on invalid argument. + * @phpstan-param callable():bool $onInvalid */ protected function genericFromBlobWithInvalidator(string $key, ?string $blob, callable $onInvalid): GenericCacheItem { @@ -157,7 +155,9 @@ protected function genericFromBlobWithInvalidator(string $key, ?string $blob, ca } /** - * @param array{value:mixed,expires:int|null} $record + * @param string $key The key argument. + * @param array $record The record argument. + * @phpstan-param array{value:mixed,expires:int|null} $record */ protected function genericItemFromRecord(string $key, array $record): GenericCacheItem { @@ -178,9 +178,11 @@ protected function genericMiss(string $key): GenericCacheItem /** * @template T of CacheItemInterface * - * @param list $keys - * @param callable(string):T $fetcher - * @return array + * @param array $keys The keys argument. + * @param callable $fetcher The fetcher argument. + * @phpstan-param list $keys + * @phpstan-param callable(string):T $fetcher + * @phpstan-return array */ protected function multiFetchItems(array $keys, callable $fetcher): array { @@ -193,7 +195,9 @@ protected function multiFetchItems(array $keys, callable $fetcher): array } /** - * @param callable(CacheItemInterface,array{ttl:int|null,expiresAt:int|null}):bool $writer + * @param CacheItemInterface $item The item argument. + * @param callable $writer The writer argument. + * @phpstan-param callable(CacheItemInterface,array{ttl:int|null,expiresAt:int|null}):bool $writer */ protected function saveEncoded(CacheItemInterface $item, callable $writer): bool { @@ -210,8 +214,12 @@ protected function saveEncoded(CacheItemInterface $item, callable $writer): bool } /** - * @param callable(string):(array{value:mixed,expires:int|null}|null) $decoder - * @param callable():bool $onInvalid + * @param string $key The key argument. + * @param string|null $encoded The encoded argument. + * @param callable $onInvalid The on invalid argument. + * @param callable $decoder The decoder argument. + * @phpstan-param callable():bool $onInvalid + * @phpstan-param callable(string):(array{value:mixed,expires:int|null}|null) $decoder */ private function genericFromEncodedWithInvalidator( string $key, diff --git a/src/Cache/Adapter/AdapterValueNormalizer.php b/src/Cache/Adapter/AdapterValueNormalizer.php index baef5aa..c9ee375 100644 --- a/src/Cache/Adapter/AdapterValueNormalizer.php +++ b/src/Cache/Adapter/AdapterValueNormalizer.php @@ -7,7 +7,8 @@ final class AdapterValueNormalizer { /** - * @return array|null + * @phpstan-return array|null + * @param mixed $value The value argument. */ public static function fromArrayLikeOrToArray(mixed $value): ?array { @@ -21,7 +22,8 @@ public static function fromArrayLikeOrToArray(mixed $value): ?array } /** - * @return array|null + * @phpstan-return array|null + * @param mixed $value The value argument. */ public static function fromJsonOrArrayLike(mixed $value): ?array { @@ -35,8 +37,9 @@ public static function fromJsonOrArrayLike(mixed $value): ?array } /** - * @param array $value - * @return array + * @param array $value The value argument. + * @phpstan-param array $value + * @phpstan-return array */ public static function normalizeAssoc(array $value): array { @@ -51,7 +54,8 @@ public static function normalizeAssoc(array $value): array } /** - * @return array|null + * @phpstan-return array|null + * @param object $value The value argument. */ private static function normalizeFromToArray(object $value): ?array { diff --git a/src/Cache/Adapter/ApcuCacheAdapter.php b/src/Cache/Adapter/ApcuCacheAdapter.php index 83cba3d..cb3fece 100644 --- a/src/Cache/Adapter/ApcuCacheAdapter.php +++ b/src/Cache/Adapter/ApcuCacheAdapter.php @@ -16,7 +16,8 @@ * in-memory caching. It's suitable for production environments where * shared memory caching is available and provides fast access to cached data. * - * Note: This adapter requires the APCu extension to be installed and enabled. + * This This adapter requires the APCu extension to be installed and enabled. + * @param string $namespace A namespace prefix to avoid key collisions. */ class ApcuCacheAdapter extends AbstractCacheAdapter { @@ -25,9 +26,9 @@ class ApcuCacheAdapter extends AbstractCacheAdapter /** * Creates a new APCu cache adapter. * - * @param string $namespace A namespace prefix to avoid key collisions. * * @throws RuntimeException If the APCu extension is not enabled. + * @param string $namespace A namespace prefix to avoid key collisions. */ public function __construct(string $namespace = 'default') { @@ -63,7 +64,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -99,8 +101,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { @@ -155,9 +158,13 @@ protected function supportsItem(CacheItemInterface $item): bool } /** - * @param array $items - * @param list $stale - * @param array $raw + * @param array $items The items argument. + * @param array $stale The stale argument. + * @param string $key The key argument. + * @param array $raw The raw argument. + * @phpstan-param array $items + * @phpstan-param list $stale + * @phpstan-param array $raw */ private function appendFetchedHit(array &$items, array &$stale, string $key, array $raw): bool { @@ -197,7 +204,7 @@ private function hitItemFromBlob(string $key, string $blob): ?ApcuCacheItem } /** - * @return list + * @phpstan-return list */ private function listKeys(): array { diff --git a/src/Cache/Adapter/ArrayCacheAdapter.php b/src/Cache/Adapter/ArrayCacheAdapter.php index 99f7198..0fd0f9f 100644 --- a/src/Cache/Adapter/ArrayCacheAdapter.php +++ b/src/Cache/Adapter/ArrayCacheAdapter.php @@ -42,7 +42,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -80,8 +81,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { diff --git a/src/Cache/Adapter/CachePayloadCodec.php b/src/Cache/Adapter/CachePayloadCodec.php index dda91be..66fcfb1 100644 --- a/src/Cache/Adapter/CachePayloadCodec.php +++ b/src/Cache/Adapter/CachePayloadCodec.php @@ -45,7 +45,8 @@ public static function configureSecurity( } /** - * @return array{value:mixed,expires:int|null}|null + * @phpstan-return array{value:mixed,expires:int|null}|null + * @param string $blob The blob argument. */ public static function decode(string $blob): ?array { @@ -103,7 +104,8 @@ public static function encode(mixed $value, ?int $expiresAt): string } /** - * @return array{ttl:int|null,expiresAt:int|null} + * @phpstan-return array{ttl:int|null,expiresAt:int|null} + * @param CacheItemInterface $item The item argument. */ public static function expirationFromItem(CacheItemInterface $item): array { @@ -153,7 +155,8 @@ private static function bootstrapSecurityFromEnvironment(): void } /** - * @return array{value:mixed,expires:int|null}|null + * @phpstan-return array{value:mixed,expires:int|null}|null + * @param mixed $decoded The decoded argument. */ private static function decodeArrayPayload(mixed $decoded): ?array { @@ -184,7 +187,8 @@ private static function decodeArrayPayload(mixed $decoded): ?array } /** - * @return array{value:mixed,expires:int|null}|null + * @phpstan-return array{value:mixed,expires:int|null}|null + * @param mixed $decoded The decoded argument. */ private static function decodeCacheItem(mixed $decoded): ?array { @@ -196,8 +200,9 @@ private static function decodeCacheItem(mixed $decoded): ?array } /** - * @param array $decoded - * @return array{value:mixed,expires:int|null}|null + * @param array $decoded The decoded argument. + * @phpstan-param array $decoded + * @phpstan-return array{value:mixed,expires:int|null}|null */ private static function decodeFormattedPayload(array $decoded): ?array { diff --git a/src/Cache/Adapter/ChainCacheAdapter.php b/src/Cache/Adapter/ChainCacheAdapter.php index 47c081f..3941a84 100644 --- a/src/Cache/Adapter/ChainCacheAdapter.php +++ b/src/Cache/Adapter/ChainCacheAdapter.php @@ -13,7 +13,9 @@ final class ChainCacheAdapter extends AbstractCacheAdapter { /** - * @param array $pools + * @param array $pools The pools argument. + * @param bool $writeToL1 The write to l1 argument. + * @phpstan-param array $pools */ public function __construct( private readonly array $pools, @@ -54,7 +56,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -100,8 +103,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { diff --git a/src/Cache/Adapter/FileCacheAdapter.php b/src/Cache/Adapter/FileCacheAdapter.php index 5378ca0..86cc741 100644 --- a/src/Cache/Adapter/FileCacheAdapter.php +++ b/src/Cache/Adapter/FileCacheAdapter.php @@ -16,6 +16,8 @@ * Each cache entry is serialized and stored with a .cache extension. * It provides a simple filesystem-based caching solution suitable for * development environments or applications without access to dedicated cache systems. + * @param string $namespace A namespace prefix for cache files to avoid collisions. + * @param string|null $baseDir The base directory for cache files. If null, uses system temp directory. */ class FileCacheAdapter extends AbstractCacheAdapter { @@ -28,10 +30,10 @@ class FileCacheAdapter extends AbstractCacheAdapter /** * Creates a new file-based cache adapter. * - * @param string $namespace A namespace prefix for cache files to avoid collisions. - * @param string|null $baseDir The base directory for cache files. If null, uses system temp directory. * * @throws RuntimeException If the cache directory cannot be created or is not writable. + * @param string $namespace A namespace prefix for cache files to avoid collisions. + * @param string|null $baseDir The base directory for cache files. If null, uses system temp directory. */ public function __construct(string $namespace = 'default', ?string $baseDir = null) { @@ -66,7 +68,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { diff --git a/src/Cache/Adapter/MemCacheAdapter.php b/src/Cache/Adapter/MemCacheAdapter.php index 6750178..2e37fbd 100644 --- a/src/Cache/Adapter/MemCacheAdapter.php +++ b/src/Cache/Adapter/MemCacheAdapter.php @@ -19,7 +19,10 @@ class MemCacheAdapter extends AbstractCacheAdapter private array $knownKeys = []; /** - * @param array $servers + * @param string $namespace The namespace argument. + * @param array $servers The servers argument. + * @param \Memcached|null $client The client argument. + * @phpstan-param array $servers */ public function __construct( string $namespace = 'default', @@ -60,7 +63,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -101,8 +105,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { @@ -168,9 +173,15 @@ protected function supportsItem(CacheItemInterface $item): bool } /** - * @param array $items - * @param list $stale - * @param list $staleLogicalKeys + * @param array $items The items argument. + * @param array $stale The stale argument. + * @param array $staleLogicalKeys The stale logical keys argument. + * @param string $logicalKey The logical key argument. + * @param string $mappedKey The mapped key argument. + * @param mixed $rawEntry The raw entry argument. + * @phpstan-param array $items + * @phpstan-param list $stale + * @phpstan-param list $staleLogicalKeys */ private function appendFetchedHit( array &$items, @@ -198,8 +209,13 @@ private function appendFetchedHit( } /** - * @param array $seen - * @param list $out + * @param string $server The server argument. + * @param int $slabId The slab id argument. + * @param string $pref The pref argument. + * @param array $seen The seen argument. + * @param array $out The out argument. + * @phpstan-param array $seen + * @phpstan-param list $out */ private function collectDumpedKeys( string $server, @@ -230,8 +246,9 @@ private function collectDumpedKeys( } /** - * @param array $items - * @return list + * @param array $items The items argument. + * @phpstan-param array $items + * @phpstan-return list */ private function extractSlabIds(array $items): array { @@ -249,7 +266,7 @@ private function extractSlabIds(array $items): array } /** - * @return list + * @phpstan-return list */ private function fastKnownKeys(): array { @@ -257,7 +274,7 @@ private function fastKnownKeys(): array } /** - * @return list + * @phpstan-return list */ private function fetchKeys(): array { @@ -290,7 +307,8 @@ private function hitItemFromBlob(string $key, string $blob): ?MemCacheItem } /** - * @return list + * @phpstan-return list + * @param string $pref The pref argument. */ private function keysFromGetAll(string $pref): array { @@ -310,7 +328,8 @@ private function keysFromGetAll(string $pref): array } /** - * @return list + * @phpstan-return list + * @param string $pref The pref argument. */ private function keysFromSlabDump(string $pref): array { @@ -339,7 +358,7 @@ private function missItem(string $key): MemCacheItem } /** - * @return array> + * @phpstan-return array> */ private function slabIdsByServer(): array { @@ -358,8 +377,10 @@ private function slabIdsByServer(): array } /** - * @param array $fullKeys - * @return list + * @param array $fullKeys The full keys argument. + * @param string $pref The pref argument. + * @phpstan-param array $fullKeys + * @phpstan-return list */ private function stripNamespace(array $fullKeys, string $pref): array { diff --git a/src/Cache/Adapter/MongoDbCacheAdapter.php b/src/Cache/Adapter/MongoDbCacheAdapter.php index 57698ba..e72a7bc 100644 --- a/src/Cache/Adapter/MongoDbCacheAdapter.php +++ b/src/Cache/Adapter/MongoDbCacheAdapter.php @@ -72,7 +72,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -111,8 +112,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { diff --git a/src/Cache/Adapter/NullCacheAdapter.php b/src/Cache/Adapter/NullCacheAdapter.php index 51deb1e..8c8f69f 100644 --- a/src/Cache/Adapter/NullCacheAdapter.php +++ b/src/Cache/Adapter/NullCacheAdapter.php @@ -29,7 +29,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -51,8 +52,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { diff --git a/src/Cache/Adapter/PdoCacheAdapter.php b/src/Cache/Adapter/PdoCacheAdapter.php index ea5b40a..04c0e49 100644 --- a/src/Cache/Adapter/PdoCacheAdapter.php +++ b/src/Cache/Adapter/PdoCacheAdapter.php @@ -103,7 +103,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -178,8 +179,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { @@ -320,7 +322,8 @@ private function createSchemaIfMissing(): void } /** - * @param array $mappedKeys + * @param array $mappedKeys The mapped keys argument. + * @phpstan-param array $mappedKeys */ private function deleteMappedItems(array $mappedKeys): void { @@ -334,8 +337,9 @@ private function deleteMappedItems(array $mappedKeys): void } /** - * @param array $mappedKeys - * @return array + * @param array $mappedKeys The mapped keys argument. + * @phpstan-param array $mappedKeys + * @phpstan-return array */ private function fetchRowsByMappedKeys(array $mappedKeys): array { @@ -372,7 +376,9 @@ private function fetchRowsByMappedKeys(array $mappedKeys): array } /** - * @param array{payload:string,expires:int|null} $row + * @param string $key The key argument. + * @param array $row The row argument. + * @phpstan-param array{payload:string,expires:int|null} $row */ private function hydrateItemFromRow(string $key, array $row): ?GenericCacheItem { @@ -419,7 +425,9 @@ private function nativeUpsertSql(): ?string } /** - * @param array{':k':string,':p':string,':e':int|null} $params + * @param array $params The params argument. + * @param string $mappedKey The mapped key argument. + * @phpstan-param array{':k':string,':p':string,':e':int|null} $params */ private function upsert(array $params, string $mappedKey): bool { diff --git a/src/Cache/Adapter/PhpFilesCacheAdapter.php b/src/Cache/Adapter/PhpFilesCacheAdapter.php index 74edd54..212df90 100644 --- a/src/Cache/Adapter/PhpFilesCacheAdapter.php +++ b/src/Cache/Adapter/PhpFilesCacheAdapter.php @@ -67,7 +67,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -107,8 +108,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { diff --git a/src/Cache/Adapter/RedisCacheAdapter.php b/src/Cache/Adapter/RedisCacheAdapter.php index 7b57b7e..46e8f09 100644 --- a/src/Cache/Adapter/RedisCacheAdapter.php +++ b/src/Cache/Adapter/RedisCacheAdapter.php @@ -16,7 +16,10 @@ * It supports both standalone Redis instances and Redis clusters, * making it suitable for production environments with multiple web servers. * - * Note: This adapter requires the phpredis extension to be installed. + * This This adapter requires the phpredis extension to be installed. + * @param string $namespace A namespace prefix to avoid key collisions. + * @param string $dsn The Redis connection DSN (e.g., 'redis://127.0.0.1:6379'). + * @param \Redis|null $client Optional pre-configured Redis client instance. */ class RedisCacheAdapter extends AbstractCacheAdapter { @@ -27,11 +30,11 @@ class RedisCacheAdapter extends AbstractCacheAdapter /** * Creates a new Redis cache adapter. * + * + * @throws RuntimeException If the phpredis extension is not loaded. * @param string $namespace A namespace prefix to avoid key collisions. * @param string $dsn The Redis connection DSN (e.g., 'redis://127.0.0.1:6379'). * @param \Redis|null $client Optional pre-configured Redis client instance. - * - * @throws RuntimeException If the phpredis extension is not loaded. */ public function __construct( string $namespace = 'default', @@ -77,7 +80,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -121,8 +125,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { diff --git a/src/Cache/Adapter/RedisClusterCacheAdapter.php b/src/Cache/Adapter/RedisClusterCacheAdapter.php index 510d4dc..8b79d4a 100644 --- a/src/Cache/Adapter/RedisClusterCacheAdapter.php +++ b/src/Cache/Adapter/RedisClusterCacheAdapter.php @@ -15,7 +15,13 @@ final class RedisClusterCacheAdapter extends AbstractCacheAdapter private readonly string $ns; /** - * @param array $seeds + * @param string $namespace The namespace argument. + * @param array $seeds The seeds argument. + * @param float $timeout The timeout argument. + * @param float $readTimeout The read timeout argument. + * @param bool $persistent The persistent argument. + * @param object|null $client The client argument. + * @phpstan-param array $seeds */ public function __construct( string $namespace = 'default', @@ -76,7 +82,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -108,8 +115,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { diff --git a/src/Cache/Adapter/ScyllaDbCacheAdapter.php b/src/Cache/Adapter/ScyllaDbCacheAdapter.php index 46d4234..5a8a2a0 100644 --- a/src/Cache/Adapter/ScyllaDbCacheAdapter.php +++ b/src/Cache/Adapter/ScyllaDbCacheAdapter.php @@ -80,7 +80,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -118,8 +119,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { @@ -158,7 +160,9 @@ private static function validateIdentifier(string $value, string $label): string } /** - * @param array $arguments + * @param string $method The method argument. + * @param array $arguments The arguments argument. + * @phpstan-param array $arguments */ private function callSession(string $method, array $arguments): mixed { @@ -186,7 +190,9 @@ private function createSchemaIfMissing(): void } /** - * @param array $arguments + * @param string $cql The cql argument. + * @param array $arguments The arguments argument. + * @phpstan-param array $arguments */ private function executeCql(string $cql, array $arguments = []): mixed { @@ -201,7 +207,8 @@ private function executeCql(string $cql, array $arguments = []): mixed } /** - * @param array $arguments + * @param array $arguments The arguments argument. + * @phpstan-param array $arguments */ private function executionOptions(array $arguments): mixed { @@ -214,8 +221,10 @@ private function executionOptions(array $arguments): mixed } /** - * @param array $arguments - * @return array|null + * @param string $cql The cql argument. + * @param array $arguments The arguments argument. + * @phpstan-param array $arguments + * @phpstan-return array|null */ private function firstRow(string $cql, array $arguments = []): ?array { @@ -247,8 +256,9 @@ private function normalizeExpiry(mixed $value): ?int } /** - * @param array $rows - * @return array> + * @param array $rows The rows argument. + * @phpstan-param array $rows + * @phpstan-return array> */ private function normalizeRows(array $rows): array { @@ -277,8 +287,10 @@ private function normalizeString(mixed $value): ?string } /** - * @param array $arguments - * @return array> + * @param string $cql The cql argument. + * @param array $arguments The arguments argument. + * @phpstan-param array $arguments + * @phpstan-return array> */ private function queryRows(string $cql, array $arguments = []): array { diff --git a/src/Cache/Adapter/SharedMemoryCacheAdapter.php b/src/Cache/Adapter/SharedMemoryCacheAdapter.php index de94af6..7647a9a 100644 --- a/src/Cache/Adapter/SharedMemoryCacheAdapter.php +++ b/src/Cache/Adapter/SharedMemoryCacheAdapter.php @@ -89,7 +89,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -124,8 +125,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { @@ -148,7 +150,7 @@ protected function supportsItem(CacheItemInterface $item): bool } /** - * @return array + * @phpstan-return array */ private function loadStore(): array { @@ -178,7 +180,8 @@ private function map(string $key): string } /** - * @param array $store + * @param array $store The store argument. + * @phpstan-param array $store */ private function store(array $store): bool { diff --git a/src/Cache/Adapter/WeakMapCacheAdapter.php b/src/Cache/Adapter/WeakMapCacheAdapter.php index 7822ca8..47e1741 100644 --- a/src/Cache/Adapter/WeakMapCacheAdapter.php +++ b/src/Cache/Adapter/WeakMapCacheAdapter.php @@ -83,7 +83,8 @@ public function deleteItem(string $key): bool } /** - * @param list $keys + * @param array $keys The keys argument. + * @phpstan-param list $keys */ public function deleteItems(array $keys): bool { @@ -138,8 +139,9 @@ public function hasItem(string $key): bool } /** - * @param list $keys - * @return array + * @param array $keys The keys argument. + * @phpstan-param list $keys + * @phpstan-return array */ public function multiFetch(array $keys): array { diff --git a/src/Cache/Cache.php b/src/Cache/Cache.php index bb1632b..e7f1bef 100644 --- a/src/Cache/Cache.php +++ b/src/Cache/Cache.php @@ -50,6 +50,8 @@ final class Cache implements CacheInterface * Cache constructor. * * @param CacheItemPoolInterface $adapter Any PSR-6 cache pool. + * @param LockProviderInterface $lockProvider The lock provider argument. + * @param CacheMetricsCollectorInterface $metrics The metrics argument. */ public function __construct( private readonly CacheItemPoolInterface $adapter, @@ -63,10 +65,10 @@ public function __construct( * This method allows accessing cached values using property syntax. * It is equivalent to calling the `get()` method with the property name. * - * @param string $name The key for which to retrieve the value. - * @return mixed The value associated with the given key. * * @throws SimpleCacheInvalidArgument|Psr6InvalidArgumentException if the key is invalid. + * @param string $name The key for which to retrieve the value. + * @phpstan-return mixed The value associated with the given key. */ public function __get(string $name): mixed { @@ -77,6 +79,7 @@ public function __get(string $name): mixed * Whether the given key is set in the cache. * * @throws Psr6InvalidArgumentException + * @param string $name The name argument. */ public function __isset(string $name): bool { @@ -90,6 +93,8 @@ public function __isset(string $name): bool * * * @throws SimpleCacheInvalidArgument if the key is invalid + * @param string $name The name argument. + * @param mixed $value The value argument. */ public function __set(string $name, mixed $value): void { @@ -101,9 +106,9 @@ public function __set(string $name, mixed $value): void * * This method deletes the cache entry associated with the given name. * - * @param string $name The name of the cache item to unset. * * @throws SimpleCacheInvalidArgument + * @param string $name The name of the cache item to unset. */ public function __unset(string $name): void { @@ -121,7 +126,8 @@ public static function apcu(string $namespace = 'default'): self } /** - * @param array $pools + * @param array $pools The pools argument. + * @phpstan-param array $pools */ public static function chain(array $pools): self { @@ -147,7 +153,7 @@ public static function file(string $namespace = 'default', ?string $dir = null): * * @param string $namespace Cache prefix. Will be suffixed to each key. * @param string|null $dir Directory to store cache files (or null → sys temp dir), used if APCu is not enabled. - * @return static An instance of the cache using the selected adapter. + * @phpstan-return static An instance of the cache using the selected adapter. */ public static function local( string $namespace = 'default', @@ -163,9 +169,10 @@ public static function local( /** * Static factory for Memcached-based cache. * - * @param string $namespace Cache prefix. Will be suffixed to each key. - * @param array $servers Memcached servers as an array of `[host, port, weight]`. * The `weight` is a float between 0 and 1, and defaults to 0. + * @param string $namespace Cache prefix. Will be suffixed to each key. + * @param array $servers Memcached servers as an array of `[host, port, weight]`. + * @phpstan-param array $servers Memcached servers as an array of `[host, port, weight]`. * @param \Memcached|null $client Optional preconfigured Memcached instance. */ public static function memcache( @@ -250,9 +257,9 @@ public static function phpFiles(string $namespace = 'default', ?string $dir = nu /** * Static factory for Redis cache. * + * or null to use the default ('redis://127.0.0.1:6379'). * @param string $namespace Cache prefix. * @param string $dsn DSN for Redis connection (e.g. 'redis://127.0.0.1:6379'), - * or null to use the default ('redis://127.0.0.1:6379'). * @param \Redis|null $client Optional preconfigured Redis instance. */ public static function redis( @@ -268,7 +275,13 @@ public static function redis( } /** - * @param array $seeds + * @param string $namespace The namespace argument. + * @param array $seeds The seeds argument. + * @param float $timeout The timeout argument. + * @param float $readTimeout The read timeout argument. + * @param bool $persistent The persistent argument. + * @param object|null $client The client argument. + * @phpstan-param array $seeds */ public static function redisCluster( string $namespace = 'default', @@ -334,7 +347,9 @@ public static function sqlite(string $namespace = 'default', ?string $file = nul /** * Builds a tiered cache from pool instances and/or descriptor arrays. * - * @param array> $tiers + * @param array $tiers The tiers argument. + * @param bool $writeToL1 The write to l1 argument. + * @phpstan-param array> $tiers */ public static function tiered(array $tiers, bool $writeToL1 = true): self { @@ -370,7 +385,6 @@ public static function weakMap(string $namespace = 'default'): self /** * Removes all items from the cache. * - * @return bool * True if the operation was successful, false otherwise. */ public function clear(): bool @@ -394,7 +408,7 @@ public function clearCache(): bool * queue. If the adapter does not support deferred cache items, this * method is a no-op. * - * @return bool True if all deferred items were successfully saved, false otherwise. + * @phpstan-return bool True if all deferred items were successfully saved, false otherwise. */ public function commit(): bool { @@ -447,6 +461,7 @@ public function count(): int * Delete an item from the cache. * * @throws SimpleCacheInvalidArgument if the key is invalid + * @param string $key The key argument. */ public function delete(string $key): bool { @@ -470,12 +485,11 @@ public function delete(string $key): bool * This method deletes the item from the cache if it exists. If the item does * not exist, it is silently ignored. * - * @param string $key * The key of the item to delete. - * @return bool * True if the item was successfully deleted, false otherwise. * * @throws Psr6InvalidArgumentException + * @param string $key The key argument. */ public function deleteItem(string $key): bool { @@ -490,10 +504,11 @@ public function deleteItem(string $key): bool /** * Deletes multiple items from the cache. * - * @param string[] $keys The array of keys to delete. - * @return bool True if all items were successfully deleted, false otherwise. * * @throws Psr6InvalidArgumentException + * @param array $keys The array of keys to delete. + * @phpstan-param string[] $keys The array of keys to delete. + * @phpstan-return bool True if all items were successfully deleted, false otherwise. */ public function deleteItems(array $keys): bool { @@ -512,9 +527,10 @@ public function deleteItems(array $keys): bool /** * Deletes multiple keys from the cache. * - * @param iterable $keys * * @throws SimpleCacheInvalidArgument if any key is invalid + * @param iterable $keys The keys argument. + * @phpstan-param iterable $keys */ public function deleteMultiple(iterable $keys): bool { @@ -533,7 +549,7 @@ public function deleteMultiple(iterable $keys): bool /** * Returns metrics grouped by readable adapter name. * - * @return array> + * @phpstan-return array> */ public function exportMetrics(): array { @@ -549,6 +565,8 @@ public function exportMetrics(): array * Fetches a value from the cache. If the key does not exist, returns $default. * * @throws SimpleCacheInvalidArgument|Psr6InvalidArgumentException if the key is invalid + * @param string $key The key argument. + * @param mixed $default The default argument. */ public function get(string $key, mixed $default = null): mixed { @@ -560,14 +578,13 @@ public function get(string $key, mixed $default = null): mixed * * This method returns a CacheItemInterface object containing the cached value. * - * @param string $key * The key of the item to retrieve. - * @return CacheItemInterface * The retrieved Cache Item. * * @throws CacheInvalidArgumentException * If the $key is invalid or if a CacheLoader is not available when * the value is not found. + * @param string $key The key argument. */ public function getItem(string $key): CacheItemInterface { @@ -584,10 +601,11 @@ public function getItem(string $key): CacheItemInterface * `multiFetch` method. Otherwise, it iterates over the keys and calls * `getItem` on each key. * - * @param string[] $keys * An array of keys to fetch from the cache. - * @return iterable * An iterable of CacheItemInterface objects. + * @param array $keys The keys argument. + * @phpstan-param string[] $keys + * @phpstan-return iterable */ public function getItems(array $keys = []): iterable { @@ -603,10 +621,11 @@ public function getItems(array $keys = []): iterable * This method is a wrapper for `getItems()`, and is intended for use with * iterators. * - * @param string[] $keys * An array of keys to fetch from the cache. - * @return iterable * An iterable of CacheItemInterface objects. + * @param array $keys The keys argument. + * @phpstan-param string[] $keys + * @phpstan-return iterable */ public function getItemsIterator(array $keys = []): iterable { @@ -616,10 +635,12 @@ public function getItemsIterator(array $keys = []): iterable /** * Obtains multiple values by their keys. * - * @param iterable $keys - * @return iterable * * @throws SimpleCacheInvalidArgument|Psr6InvalidArgumentException if any key is invalid + * @param iterable $keys The keys argument. + * @param mixed $default The default argument. + * @phpstan-param iterable $keys + * @phpstan-return iterable */ public function getMultiple(iterable $keys, mixed $default = null): iterable { @@ -637,6 +658,7 @@ public function getMultiple(iterable $keys, mixed $default = null): iterable * Determines whether an item exists in the cache. * * @throws Psr6InvalidArgumentException if the key is invalid + * @param string $key The key argument. */ public function has(string $key): bool { @@ -646,12 +668,11 @@ public function has(string $key): bool /** * Checks if an item is present in the cache. * - * @param string $key * The key to check. - * @return bool * True if the item exists in the cache, false otherwise. * * @throws Psr6InvalidArgumentException + * @param string $key The key argument. */ public function hasItem(string $key): bool { @@ -664,11 +685,11 @@ public function hasItem(string $key): bool * This method removes all cache items that have been tagged with the given tag. * It uses an internal tag index to efficiently locate and invalidate tagged entries. * - * @param string $tag The tag to invalidate. All cache entries with this tag will be removed. - * @return bool True if the operation was successful, false otherwise. * * @throws CacheInvalidArgumentException If the tag is invalid. * @throws Psr6InvalidArgumentException If there's an issue with cache operations. + * @param string $tag The tag to invalidate. All cache entries with this tag will be removed. + * @phpstan-return bool True if the operation was successful, false otherwise. */ public function invalidateTag(string $tag): bool { @@ -685,11 +706,12 @@ public function invalidateTag(string $tag): bool * associated with that tag. The operation is successful only if all tags * are successfully invalidated. * - * @param array $tags An array of tags to invalidate. - * @return bool True if all tags were successfully invalidated, false if any failed. * * @throws CacheInvalidArgumentException If any tag is invalid. * @throws Psr6InvalidArgumentException If there's an issue with cache operations. + * @param array $tags An array of tags to invalidate. + * @phpstan-param array $tags An array of tags to invalidate. + * @phpstan-return bool True if all tags were successfully invalidated, false if any failed. */ public function invalidateTags(array $tags): bool { @@ -715,11 +737,12 @@ public function invalidateTags(array $tags): bool * * {@inheritdoc} * - * @param string $offset * * @throws Psr6InvalidArgumentException * * @see has() + * @param mixed $offset The offset argument. + * @phpstan-param string $offset */ public function offsetExists(mixed $offset): bool { @@ -732,10 +755,11 @@ public function offsetExists(mixed $offset): bool * This method allows the use of array-like syntax to retrieve a value * from the cache. The offset is converted to a string before retrieval. * - * @param string $offset The key at which to retrieve the value. - * @return mixed The value at the specified offset. * * @throws SimpleCacheInvalidArgument|Psr6InvalidArgumentException if the key is invalid + * @param mixed $offset The key at which to retrieve the value. + * @phpstan-param string $offset The key at which to retrieve the value. + * @phpstan-return mixed The value at the specified offset. */ public function offsetGet(mixed $offset): mixed { @@ -749,10 +773,11 @@ public function offsetGet(mixed $offset): mixed * in the cache. The offset is converted to a string before storing. * The time-to-live (TTL) for the cache entry is set to null by default. * - * @param string $offset The key at which to set the value. - * @param mixed $value The value to be stored at the specified offset. * * @throws SimpleCacheInvalidArgument if the key is invalid + * @param mixed $offset The key at which to set the value. + * @phpstan-param string $offset The key at which to set the value. + * @param mixed $value The value to be stored at the specified offset. */ public function offsetSet(mixed $offset, mixed $value): void { @@ -762,9 +787,10 @@ public function offsetSet(mixed $offset, mixed $value): void /** * Unsets a key from the cache. * - * @param string $offset * * @throws Psr6InvalidArgumentException|SimpleCacheInvalidArgument if the key is invalid + * @param mixed $offset The offset argument. + * @phpstan-param string $offset */ public function offsetUnset(mixed $offset): void { @@ -776,6 +802,12 @@ public function offsetUnset(mixed $offset): void * * On cache miss, this acquires a host-local lock, re-checks cache, computes, * applies jittered TTL, persists, and returns the computed value. + * + * @param string $key The key argument. + * @param callable $resolver The resolver argument. + * @param mixed $ttl The ttl argument. + * @param array $tags The tags argument. + * @phpstan-param array $tags */ public function remember( string $key, @@ -792,13 +824,12 @@ public function remember( * This method will throw a Psr6InvalidArgumentException if the item does not * implement CacheItemInterface. * - * @param CacheItemInterface $item * The cache item to persist. - * @return bool * True if the cache item was successfully persisted, false otherwise. * * @throws Psr6InvalidArgumentException * If the item does not implement CacheItemInterface. + * @param CacheItemInterface $item The item argument. */ public function save(CacheItemInterface $item): bool { @@ -812,7 +843,7 @@ public function save(CacheItemInterface $item): bool * `commit()` method is invoked. It does not persist the item immediately. * * @param CacheItemInterface $item The cache item to defer. - * @return bool True if the item was successfully deferred, false if the item type is invalid. + * @phpstan-return bool True if the item was successfully deferred, false if the item type is invalid. */ public function saveDeferred(CacheItemInterface $item): bool { @@ -822,9 +853,12 @@ public function saveDeferred(CacheItemInterface $item): bool /** * Persists a value in the cache, optionally with a TTL. * - * @param int|DateInterval|null $ttl Time-to-live in seconds or a DateInterval * * @throws SimpleCacheInvalidArgument if the key or TTL is invalid + * @param mixed $ttl Time-to-live in seconds or a DateInterval + * @param string $key The key argument. + * @param mixed $value The value argument. + * @phpstan-param int|DateInterval|null $ttl Time-to-live in seconds or a DateInterval */ public function set(string $key, mixed $value, mixed $ttl = null): bool { @@ -880,10 +914,12 @@ public function setMetricsExportHook(?callable $hook): self /** * Persists multiple key ⇒ value pairs to the cache. * - * @param iterable $values key ⇒ value mapping - * @param int|DateInterval|null $ttl TTL for all items * * @throws SimpleCacheInvalidArgument if any key is invalid + * @param iterable $values key ⇒ value mapping + * @phpstan-param iterable $values key ⇒ value mapping + * @param mixed $ttl TTL for all items + * @phpstan-param int|DateInterval|null $ttl TTL for all items */ public function setMultiple(iterable $values, mixed $ttl = null): bool { @@ -905,13 +941,12 @@ public function setMultiple(iterable $values, mixed $ttl = null): bool /** * Changes the namespace and directory for the pool. * - * If the adapter implements {@see CacheItemPoolInterface::setNamespaceAndDirectory}, - * this call is forwarded to the adapter. Otherwise, a {@see BadMethodCallException} is thrown. + * If the adapter supports namespace and directory switching, this call is + * forwarded to it. Otherwise, a {@see BadMethodCallException} is thrown. * + * @throws BadMethodCallException if the adapter does not support this method. * @param string $namespace The new namespace. * @param string|null $dir The new directory, or null to use the default. - * - * @throws BadMethodCallException if the adapter does not support this method. */ public function setNamespaceAndDirectory(string $namespace, ?string $dir = null): void { @@ -933,14 +968,16 @@ public function setNamespaceAndDirectory(string $namespace, ?string $dir = null) * Tags provide a way to group related cache items and invalidate them * together when the underlying data changes. * - * @param string $key The cache key under which to store the value. - * @param mixed $value The value to store in the cache. - * @param array $tags An array of tags to associate with this cache entry. - * @param int|DateInterval|null $ttl Optional time-to-live for the cache entry. - * @return bool True if the operation was successful, false otherwise. * * @throws CacheInvalidArgumentException If the key or tags are invalid. * @throws SimpleCacheInvalidArgument If the key or TTL is invalid. + * @param string $key The cache key under which to store the value. + * @param mixed $value The value to store in the cache. + * @param array $tags An array of tags to associate with this cache entry. + * @phpstan-param array $tags An array of tags to associate with this cache entry. + * @param mixed $ttl Optional time-to-live for the cache entry. + * @phpstan-param int|DateInterval|null $ttl Optional time-to-live for the cache entry. + * @phpstan-return bool True if the operation was successful, false otherwise. */ public function setTagged(string $key, mixed $value, array $tags, mixed $ttl = null): bool { @@ -1068,8 +1105,9 @@ private function normalizeTag(string $tag): string } /** - * @param array $tags - * @return array + * @param array $tags The tags argument. + * @phpstan-param array $tags + * @phpstan-return array */ private function normalizeTagList(array $tags): array { @@ -1083,6 +1121,7 @@ private function normalizeTagList(array $tags): array /** * Converts a PSR-16 TTL (int|DateInterval|null) into an integer number of seconds. + * @param mixed $ttl The ttl argument. */ private function normalizeTtl(mixed $ttl): ?int { @@ -1142,8 +1181,9 @@ private function readableAdapterName(string $adapterClass): string } /** - * @param array> $snapshot - * @return array> + * @param array $snapshot The snapshot argument. + * @phpstan-param array> $snapshot + * @phpstan-return array> */ private function readableMetricsSnapshot(array $snapshot): array { @@ -1178,6 +1218,7 @@ private function tagVersionKey(string $normalizedTag): string * Validates a cache key per PSR-16 rules (and reuses for PSR-6). * * @throws CacheInvalidArgumentException if the key is invalid. + * @param string $key The key argument. */ private function validateKey(string $key): void { @@ -1189,7 +1230,10 @@ private function validateKey(string $key): void } /** - * @param array $tags + * @param string $key The key argument. + * @param array $tags The tags argument. + * @param int|null $ttl The ttl argument. + * @phpstan-param array $tags */ private function writeTagMeta(string $key, array $tags, ?int $ttl): bool { diff --git a/src/Cache/CacheInterface.php b/src/Cache/CacheInterface.php index 2c47f94..804d405 100644 --- a/src/Cache/CacheInterface.php +++ b/src/Cache/CacheInterface.php @@ -26,6 +26,8 @@ * invalidation, cache stampede protection, and multiple storage adapters. * * @extends ArrayAccess + * @return array + * @phpstan-return array> */ interface CacheInterface extends ArrayAccess, CacheItemPoolInterface, Countable, SimpleCacheInterface { @@ -44,19 +46,24 @@ public function configureSerializationSecurity( * Returns metrics grouped by readable adapter name (for example ``file``, * ``pdo``, ``redis``) and metric name. * - * @return array> + * @phpstan-return array> */ public function exportMetrics(): array; public function invalidateTag(string $tag): bool; /** - * @param array $tags + * @param array $tags The tags argument. + * @phpstan-param array $tags */ public function invalidateTags(array $tags): bool; /** - * @param array $tags + * @param string $key The key argument. + * @param callable $resolver The resolver argument. + * @param mixed $ttl The ttl argument. + * @param array $tags The tags argument. + * @phpstan-param array $tags */ public function remember(string $key, callable $resolver, mixed $ttl = null, array $tags = []): mixed; @@ -67,7 +74,11 @@ public function setMetricsCollector(CacheMetricsCollectorInterface $metrics): se public function setMetricsExportHook(?callable $hook): self; /** - * @param array $tags + * @param string $key The key argument. + * @param mixed $value The value argument. + * @param array $tags The tags argument. + * @param mixed $ttl The ttl argument. + * @phpstan-param array $tags */ public function setTagged(string $key, mixed $value, array $tags, mixed $ttl = null): bool; diff --git a/src/Cache/CacheReadRememberTrait.php b/src/Cache/CacheReadRememberTrait.php index 287a176..7205607 100644 --- a/src/Cache/CacheReadRememberTrait.php +++ b/src/Cache/CacheReadRememberTrait.php @@ -60,8 +60,9 @@ public function getItem(string $key): CacheItemInterface } /** - * @param string[] $keys - * @return iterable + * @param array $keys The keys argument. + * @phpstan-param string[] $keys + * @phpstan-return iterable */ public function getItems(array $keys = []): iterable { @@ -130,6 +131,11 @@ public function hasItem(string $key): bool /** * @throws Psr6InvalidArgumentException + * @param string $key The key argument. + * @param callable $resolver The resolver argument. + * @param mixed $ttl The ttl argument. + * @param array $tags The tags argument. + * @phpstan-param array $tags */ public function remember( string $key, diff --git a/src/Cache/Item/AbstractCacheItem.php b/src/Cache/Item/AbstractCacheItem.php index 404c8c7..b4cb2f9 100644 --- a/src/Cache/Item/AbstractCacheItem.php +++ b/src/Cache/Item/AbstractCacheItem.php @@ -21,6 +21,11 @@ * * Cache items represent individual entries in a cache pool and provide * methods for accessing and manipulating their state. + * @param InternalCachePoolInterface|null $pool The cache pool this item belongs to. + * @param string $key The cache key for this item. + * @param mixed $value The cached value. + * @param bool $hit Whether this item was a cache hit. + * @param DateTimeInterface|null $exp The expiration time for this item. */ abstract class AbstractCacheItem implements CacheItemInterface { @@ -52,9 +57,9 @@ public function __serialize(): array } /** - * @param array{key:string,value:mixed,hit:bool,exp?:string|null} $data - * * @throws Exception + * @param array $data The data argument. + * @phpstan-param array{key:string,value:mixed,hit:bool,exp?:string|null} $data */ public function __unserialize(array $data): void { diff --git a/src/Cache/Item/FileCacheItem.php b/src/Cache/Item/FileCacheItem.php index 953a9b3..0438a1c 100644 --- a/src/Cache/Item/FileCacheItem.php +++ b/src/Cache/Item/FileCacheItem.php @@ -4,12 +4,4 @@ namespace Infocyph\CacheLayer\Cache\Item; -/** - * File-based cache item implementation. - * - * This class extends AbstractCacheItem to provide cache items specifically - * designed for use with the FileCacheAdapter. It inherits all - * standard PSR-6 cache item functionality while being optimized - * for filesystem-based storage. - */ final class FileCacheItem extends AbstractCacheItem {} diff --git a/src/Cache/Lock/FileLockProvider.php b/src/Cache/Lock/FileLockProvider.php index d8f95b4..980336b 100644 --- a/src/Cache/Lock/FileLockProvider.php +++ b/src/Cache/Lock/FileLockProvider.php @@ -78,7 +78,7 @@ public function release(?LockHandle $handle): void } /** - * @return array + * @phpstan-return array */ private static function &activeRegistry(): array { @@ -98,7 +98,8 @@ private static function generateToken(): ?string } /** - * @return resource|false + * @phpstan-return resource|false + * @param string $path The path argument. */ private function openLockFile(string $path): mixed { diff --git a/src/Cache/Lock/PollingLockProviderHelpers.php b/src/Cache/Lock/PollingLockProviderHelpers.php index 51f2f66..7e27813 100644 --- a/src/Cache/Lock/PollingLockProviderHelpers.php +++ b/src/Cache/Lock/PollingLockProviderHelpers.php @@ -14,7 +14,11 @@ protected static function normalizeRetrySleepMicros(int $retrySleepMicros): int } /** - * @param callable(string,string):bool $attemptAcquire + * @param string $prefix The prefix argument. + * @param string $key The key argument. + * @param float $waitSeconds The wait seconds argument. + * @param callable $attemptAcquire The attempt acquire argument. + * @phpstan-param callable(string,string):bool $attemptAcquire */ protected function acquireWithRetry( string $prefix, @@ -43,7 +47,9 @@ protected function acquireWithRetry( } /** - * @param callable(LockHandle):void $releaser + * @param LockHandle|null $handle The handle argument. + * @param callable $releaser The releaser argument. + * @phpstan-param callable(LockHandle):void $releaser */ protected function releaseWithGuard(?LockHandle $handle, callable $releaser): void { diff --git a/src/Cache/Metrics/CacheMetricsCollectorInterface.php b/src/Cache/Metrics/CacheMetricsCollectorInterface.php index 116ed76..92b24fa 100644 --- a/src/Cache/Metrics/CacheMetricsCollectorInterface.php +++ b/src/Cache/Metrics/CacheMetricsCollectorInterface.php @@ -7,7 +7,7 @@ interface CacheMetricsCollectorInterface { /** - * @return array> + * @phpstan-return array> */ public function export(): array; diff --git a/src/Cache/Tiering/TieredPoolFactory.php b/src/Cache/Tiering/TieredPoolFactory.php index 7528901..484dcf9 100644 --- a/src/Cache/Tiering/TieredPoolFactory.php +++ b/src/Cache/Tiering/TieredPoolFactory.php @@ -11,8 +11,9 @@ final class TieredPoolFactory { /** - * @param array $tiers - * @return array + * @param array $tiers The tiers argument. + * @phpstan-param array $tiers + * @phpstan-return array */ public static function fromArray(array $tiers): array { @@ -29,7 +30,10 @@ public static function fromArray(array $tiers): array } /** - * @param array $descriptor + * @param array $descriptor The descriptor argument. + * @param string $key The key argument. + * @param bool $default The default argument. + * @phpstan-param array $descriptor */ private static function bool(array $descriptor, string $key, bool $default): bool { @@ -56,7 +60,9 @@ private static function buildScyllaSession(string $keyspace): object } /** - * @param array $descriptor + * @param array $descriptor The descriptor argument. + * @param int|string $index The index argument. + * @phpstan-param array $descriptor */ private static function descriptorToPool(array $descriptor, int|string $index): CacheItemPoolInterface { @@ -137,7 +143,10 @@ private static function descriptorToPool(array $descriptor, int|string $index): } /** - * @param array $descriptor + * @param array $descriptor The descriptor argument. + * @param string $key The key argument. + * @param float $default The default argument. + * @phpstan-param array $descriptor */ private static function float(array $descriptor, string $key, float $default): float { @@ -156,7 +165,10 @@ private static function float(array $descriptor, string $key, float $default): f } /** - * @param array $descriptor + * @param array $descriptor The descriptor argument. + * @param string $key The key argument. + * @param int $default The default argument. + * @phpstan-param array $descriptor */ private static function int(array $descriptor, string $key, int $default): int { @@ -186,7 +198,11 @@ private static function memcachedClient(mixed $client, int|string $index): ?\Mem } /** - * @param array $descriptor + * @param array $descriptor The descriptor argument. + * @param string $namespace The namespace argument. + * @param mixed $client The client argument. + * @param int|string $index The index argument. + * @phpstan-param array $descriptor */ private static function mongoPool(array $descriptor, string $namespace, mixed $client, int|string $index): CacheItemPoolInterface { @@ -210,8 +226,9 @@ private static function mongoPool(array $descriptor, string $namespace, mixed $c } /** - * @param array $tier - * @return array + * @param array $tier The tier argument. + * @phpstan-param array $tier + * @phpstan-return array */ private static function normalizeDescriptor(array $tier): array { @@ -233,7 +250,9 @@ private static function normalizeDescriptor(array $tier): array } /** - * @param array $descriptor + * @param array $descriptor The descriptor argument. + * @param string $keys The keys argument. + * @phpstan-param array $descriptor */ private static function nullableString(array $descriptor, string ...$keys): ?string { @@ -313,7 +332,8 @@ private static function resolvePool(mixed $tier, int|string $index): CacheItemPo } /** - * @return array + * @phpstan-return array + * @param mixed $value The value argument. */ private static function seeds(mixed $value): array { @@ -344,7 +364,8 @@ private static function seeds(mixed $value): array } /** - * @return array + * @phpstan-return array + * @param mixed $value The value argument. */ private static function servers(mixed $value): array { @@ -383,7 +404,8 @@ private static function servers(mixed $value): array } /** - * @param array $descriptor + * @param array $descriptor The descriptor argument. + * @phpstan-param array $descriptor */ private static function sqliteDsn(array $descriptor): ?string { @@ -393,7 +415,10 @@ private static function sqliteDsn(array $descriptor): ?string } /** - * @param array $descriptor + * @param array $descriptor The descriptor argument. + * @param string $key The key argument. + * @param string $default The default argument. + * @phpstan-param array $descriptor */ private static function string(array $descriptor, string $key, string $default): string { @@ -408,8 +433,13 @@ private static function string(array $descriptor, string $key, string $default): } /** - * @param array $descriptor - * @param callable(mixed): bool $validator + * @param array $descriptor The descriptor argument. + * @param string $key The key argument. + * @param mixed $default The default argument. + * @param callable $validator The validator argument. + * @param string $expectedType The expected type argument. + * @phpstan-param array $descriptor + * @phpstan-param callable(mixed): bool $validator */ private static function typedValue( array $descriptor, diff --git a/src/Memoize/Memoizer.php b/src/Memoize/Memoizer.php index 7c22d37..e199c3b 100644 --- a/src/Memoize/Memoizer.php +++ b/src/Memoize/Memoizer.php @@ -43,9 +43,10 @@ public function flush(): void } /** - * @param array $params - * * @throws ReflectionException + * @param callable $callable The callable argument. + * @param array $params The params argument. + * @phpstan-param array $params */ public function get(callable $callable, array $params = []): mixed { @@ -68,9 +69,11 @@ public function get(callable $callable, array $params = []): mixed } /** - * @param array $params - * * @throws ReflectionException + * @param object $object The object argument. + * @param callable $callable The callable argument. + * @param array $params The params argument. + * @phpstan-param array $params */ public function getFor(object $object, callable $callable, array $params = []): mixed { @@ -95,7 +98,7 @@ public function getFor(object $object, callable $callable, array $params = []): } /** - * @return array{hits:int,misses:int,total:int} + * @phpstan-return array{hits:int,misses:int,total:int} */ public function stats(): array { @@ -107,7 +110,9 @@ public function stats(): array } /** - * @param array $params + * @param string $signature The signature argument. + * @param array $params The params argument. + * @phpstan-param array $params */ private static function buildCacheKey(string $signature, array $params): string { @@ -122,6 +127,7 @@ private static function buildCacheKey(string $signature, array $params): string /** * @throws ReflectionException + * @param callable $callable The callable argument. */ private static function callableSignature(callable $callable): string { diff --git a/src/Serializer/ValueSerializer.php b/src/Serializer/ValueSerializer.php index 5aefd32..4b6caa9 100644 --- a/src/Serializer/ValueSerializer.php +++ b/src/Serializer/ValueSerializer.php @@ -49,11 +49,11 @@ public static function configureSecurity( /** * Decode a payload produced by {@see encode()}. * - * @param string $payload The encoded string - * @param bool $base64 True ⇒ expect base64; false ⇒ raw - * @return mixed Original value * * @throws InvalidArgumentException Forwarded from ::unserialize() + * @param string $payload The encoded string + * @param bool $base64 True ⇒ expect base64; false ⇒ raw + * @phpstan-return mixed Original value */ public static function decode(string $payload, bool $base64 = true): mixed { @@ -69,16 +69,15 @@ public static function decode(string $payload, bool $base64 = true): mixed /** * Encode any value into a transport-safe (optionally base64) string. * - * ```php + * Example: * $token = ValueSerializer::encode($payload); // base64 by default * $same = ValueSerializer::decode($token); - * ``` * - * @param mixed $value Any PHP value - * @param bool $base64 True ⇒ wrap with base64; false ⇒ raw - * @return string Encoded payload * * @throws InvalidArgumentException Forwarded from ::serialize() + * @param mixed $value Any PHP value + * @param bool $base64 True ⇒ wrap with base64; false ⇒ raw + * @phpstan-return string Encoded payload */ public static function encode(mixed $value, bool $base64 = true): string { @@ -95,7 +94,7 @@ public static function encode(mixed $value, bool $base64 = true): string * Opis closures. * * @param string $str The string to check. - * @return bool True if the string is a serialized Opis closure, false otherwise. + * @phpstan-return bool True if the string is a serialized Opis closure, false otherwise. */ public static function isSerializedClosure(string $str): bool { @@ -122,11 +121,11 @@ public static function isSerializedClosure(string $str): bool * 2. `restoreFn`: takes the array (or other serializable value) returned * by `wrapFn` and returns a resource of type `$type`. * + * + * @throws InvalidArgumentException If a handler for `$type` already exists. * @param string $type The type of resource this handler is for. * @param callable $wrapFn The callable that wraps the resource. * @param callable $restoreFn The callable that restores the resource. - * - * @throws InvalidArgumentException If a handler for `$type` already exists. */ public static function registerResourceHandler( string $type, @@ -150,10 +149,10 @@ public static function registerResourceHandler( * resource handlers, and serializes it into a string using Opis Closure's * serialize function. * - * @param mixed $value The value to be serialized, which may contain resources. - * @return string The serialized string representation of the value. * * @throws InvalidArgumentException If a resource type has no registered handler. + * @param mixed $value The value to be serialized, which may contain resources. + * @phpstan-return string The serialized string representation of the value. */ public static function serialize(mixed $value): string { @@ -176,7 +175,7 @@ public static function serialize(mixed $value): string * within the resulting value using registered resource handlers. * * @param string $blob The serialized string to be converted back to its original form. - * @return mixed The original value, with any resources restored. + * @phpstan-return mixed The original value, with any resources restored. */ public static function unserialize(string $blob): mixed { @@ -205,7 +204,7 @@ public static function unserialize(string $blob): mixed * involve serialisation. * * @param mixed $resource A value that may contain wrapped resources. - * @return mixed The same value with any wrapped resources restored. + * @phpstan-return mixed The same value with any wrapped resources restored. */ public static function unwrap(mixed $resource): mixed { @@ -236,7 +235,7 @@ public static function useStrictSecurity(): void * resource handlers. * * @param mixed $value The value to be wrapped, which may contain resources. - * @return mixed The value with any resources wrapped, or the original value if no resources are found. + * @phpstan-return mixed The value with any resources wrapped, or the original value if no resources are found. */ public static function wrap(mixed $value): mixed { @@ -306,13 +305,7 @@ private static function requiresOpisSerialization(mixed $value): bool return false; } - foreach ($value as $item) { - if (self::requiresOpisSerialization($item)) { - return true; - } - } - - return false; + return array_any($value, fn($item) => self::requiresOpisSerialization($item)); } /** @@ -320,7 +313,7 @@ private static function requiresOpisSerialization(mixed $value): bool * that were wrapped by {@see wrapRecursive}. * * @param mixed $resource A value that may contain wrapped resources. - * @return mixed The same value with any wrapped resources restored. + * @phpstan-return mixed The same value with any wrapped resources restored. */ private static function unwrapRecursive(mixed $resource): mixed { @@ -355,10 +348,10 @@ private static function unwrapRecursive(mixed $resource): mixed * If the value is an array, the method recursively processes each * element in the array. * - * @param mixed $resource The value to be wrapped, which may contain resources. - * @return mixed The value with any resources wrapped, or the original value if no resources are found. * * @throws InvalidArgumentException If no handler is registered for a resource type. + * @param mixed $resource The value to be wrapped, which may contain resources. + * @phpstan-return mixed The value with any resources wrapped, or the original value if no resources are found. */ private static function wrapRecursive(mixed $resource): mixed {