infocyph · abmmhasan · Jun 22, 2026 · Jun 22, 2026
@@ -16,3 +16,4 @@ patch.php
 test.php
 var
 vendor
+.codex
@@ -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<string, CacheItemInterface> */
@@ -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<string> $keys
-     * @return iterable<string, CacheItemInterface>
+     * @param array $keys The keys argument.
+     * @phpstan-param list<string> $keys
+     * @phpstan-return iterable<string, CacheItemInterface>
      */
     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,15 +144,20 @@ 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
     {
         return $this->genericFromEncodedWithInvalidator($key, $blob, $onInvalid, $this->decodeRecordFromBlob(...));
     }
 
     /**
-     * @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<string> $keys
-     * @param callable(string):T $fetcher
-     * @return array<string, T>
+     * @param array $keys The keys argument.
+     * @param callable $fetcher The fetcher argument.
+     * @phpstan-param list<string> $keys
+     * @phpstan-param callable(string):T $fetcher
+     * @phpstan-return array<string, T>
      */
     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,

@@ -7,7 +7,8 @@
 final class AdapterValueNormalizer
 {
     /**
-     * @return array<string, mixed>|null
+     * @phpstan-return array<string, mixed>|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<string, mixed>|null
+     * @phpstan-return array<string, mixed>|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<mixed, mixed> $value
-     * @return array<string, mixed>
+     * @param array $value The value argument.
+     * @phpstan-param array<mixed, mixed> $value
+     * @phpstan-return array<string, mixed>
      */
     public static function normalizeAssoc(array $value): array
     {
@@ -51,7 +54,8 @@ public static function normalizeAssoc(array $value): array
     }
 
     /**
-     * @return array<string, mixed>|null
+     * @phpstan-return array<string, mixed>|null
+ * @param object $value The value argument.
      */
     private static function normalizeFromToArray(object $value): ?array
     {

@@ -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<string> $keys
+     * @param array $keys The keys argument.
+     * @phpstan-param list<string> $keys
      */
     public function deleteItems(array $keys): bool
     {
@@ -99,8 +101,9 @@ public function hasItem(string $key): bool
     }
 
     /**
-     * @param list<string> $keys
-     * @return array<string, ApcuCacheItem>
+     * @param array $keys The keys argument.
+     * @phpstan-param list<string> $keys
+     * @phpstan-return array<string, ApcuCacheItem>
      */
     public function multiFetch(array $keys): array
     {
@@ -155,9 +158,13 @@ protected function supportsItem(CacheItemInterface $item): bool
     }
 
     /**
-     * @param array<string, ApcuCacheItem> $items
-     * @param list<string> $stale
-     * @param array<mixed> $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<string, ApcuCacheItem> $items
+     * @phpstan-param list<string> $stale
+     * @phpstan-param array<mixed> $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<string>
+     * @phpstan-return list<string>
      */
     private function listKeys(): array
     {

@@ -42,7 +42,8 @@ public function deleteItem(string $key): bool
     }
 
     /**
-     * @param list<string> $keys
+     * @param array $keys The keys argument.
+     * @phpstan-param list<string> $keys
      */
     public function deleteItems(array $keys): bool
     {
@@ -80,8 +81,9 @@ public function hasItem(string $key): bool
     }
 
     /**
-     * @param list<string> $keys
-     * @return array<string, GenericCacheItem>
+     * @param array $keys The keys argument.
+     * @phpstan-param list<string> $keys
+     * @phpstan-return array<string, GenericCacheItem>
      */
     public function multiFetch(array $keys): array
     {

@@ -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<string, mixed> $decoded
-     * @return array{value:mixed,expires:int|null}|null
+     * @param array $decoded The decoded argument.
+     * @phpstan-param array<string, mixed> $decoded
+     * @phpstan-return array{value:mixed,expires:int|null}|null
      */
     private static function decodeFormattedPayload(array $decoded): ?array
     {

@@ -13,7 +13,9 @@
 final class ChainCacheAdapter extends AbstractCacheAdapter
 {
     /**
-     * @param array<int, CacheItemPoolInterface> $pools
+     * @param array $pools The pools argument.
+     * @param bool $writeToL1 The write to l1 argument.
+     * @phpstan-param array<int, CacheItemPoolInterface> $pools
      */
     public function __construct(
         private readonly array $pools,
@@ -54,7 +56,8 @@ public function deleteItem(string $key): bool
     }
 
     /**
-     * @param list<string> $keys
+     * @param array $keys The keys argument.
+     * @phpstan-param list<string> $keys
      */
     public function deleteItems(array $keys): bool
     {
@@ -100,8 +103,9 @@ public function hasItem(string $key): bool
     }
 
     /**
-     * @param list<string> $keys
-     * @return array<string, GenericCacheItem>
+     * @param array $keys The keys argument.
+     * @phpstan-param list<string> $keys
+     * @phpstan-return array<string, GenericCacheItem>
      */
     public function multiFetch(array $keys): array
     {

@@ -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<string> $keys
+     * @param array $keys The keys argument.
+     * @phpstan-param list<string> $keys
      */
     public function deleteItems(array $keys): bool
     {
-Original file line number
+Diff line change
@@ Expand Up / @@ -16,3 +16,4 @@ patch.php @@
     test.php
     var
     vendor
+    .codex