Refactor cache interface and implementations to return boolean for set method; update response type hints in caching methods

Author: Thavarshan

src/Fetch/Cache/CacheInterface.php

@@ -21,8 +21,15 @@ public function get(string $key): ?CachedResponse;
      * Store a response in the cache.
      *
      * @param  string  $key  The cache key
-     * @param  CachedResponse  $response  The response to cache
-     * @param  int|null  $ttl  Time to live in seconds:
+     * @param  CachedResponse  $cachedResponse  The response to cache
+     * @param  int|null  $ttl  Time to live in seconds
+     * @return bool True if the item was stored, false otherwise
+     */
+    public function set(string $key, CachedResponse $cachedResponse, ?int $ttl = null): bool;
+
+    /**
+     * Delete a cached response by key.
+     *
      * @param  string  $key  The cache key
      * @return bool True if the item was deleted, false otherwise
      */

src/Fetch/Cache/FileCache.php

@@ -89,7 +89,7 @@ public function get(string $key): ?CachedResponse
     /**
      * {@inheritdoc}
      */
-    public function set(string $key, CachedResponse $response, ?int $ttl = null): void
+    public function set(string $key, CachedResponse $response, ?int $ttl = null): bool
     {
         $this->ensureDirectoryExists();
 
@@ -144,6 +144,8 @@ public function set(string $key, CachedResponse $response, ?int $ttl = null): vo
         if ($result === false) {
             throw new RuntimeException("Failed to write cache file: {$path}");
         }
+
+        return true;
     }
 
     /**

src/Fetch/Cache/MemoryCache.php

@@ -59,7 +59,7 @@ public function get(string $key): ?CachedResponse
     /**
      * {@inheritdoc}
      */
-    public function set(string $key, CachedResponse $response, ?int $ttl = null): void
+    public function set(string $key, CachedResponse $response, ?int $ttl = null): bool
     {
         // Ensure we don't exceed max items
         if (count($this->cache) >= $this->maxItems && ! isset($this->cache[$key])) {
@@ -83,6 +83,8 @@ public function set(string $key, CachedResponse $response, ?int $ttl = null): vo
             'response' => $response,
             'expires_at' => $expiresAt,
         ];
+
+        return true;
     }
 
     /**

src/Fetch/Concerns/ManagesCache.php

@@ -11,6 +11,7 @@
 use Fetch\Cache\MemoryCache;
 use Fetch\Http\Response;
 use Fetch\Interfaces\ClientHandler;
+use Fetch\Interfaces\Response as ResponseInterface;
 
 /**
  * Trait for managing HTTP caching.
@@ -188,7 +189,7 @@ protected function getCachedResponse(string $method, string $uri, array $options
      *
      * @param  array<string, mixed>  $options  Request options
      */
-    protected function cacheResponse(string $method, string $uri, Response $response, array $options = []): void
+    protected function cacheResponse(string $method, string $uri, ResponseInterface $response, array $options = []): void
     {
         if ($this->cache === null || ! $this->isCacheableMethod($method)) {
             return;
@@ -225,7 +226,7 @@ protected function cacheResponse(string $method, string $uri, Response $response
      *
      * @param  array<string, mixed>  $options  Request options
      */
-    protected function calculateTtl(Response $response, CacheControl $cacheControl, array $options = []): ?int
+    protected function calculateTtl(ResponseInterface $response, CacheControl $cacheControl, array $options = []): ?int
     {
         // Check for per-request TTL
         $cacheConfig = $options['cache'] ?? [];
@@ -280,7 +281,7 @@ protected function addConditionalHeaders(array $options, ?CachedResponse $cached
     /**
      * Handle a 304 Not Modified response.
      */
-    protected function handleNotModified(CachedResponse $cached, Response $response): Response
+    protected function handleNotModified(CachedResponse $cached, ResponseInterface $response): Response
     {
         // Create a new response with the cached body but potentially updated headers
         $headers = $cached->getHeaders();

src/Fetch/Concerns/PerformsHttpRequests.php

@@ -273,7 +273,7 @@ public function getEffectiveTimeout(): int
      * @param  array<string, mixed>  $options  The Guzzle options
      * @param  float  $startTime  The request start time
      * @param  array<string, mixed>|null  $cachedResult  The cached result data
-     * @param  mixed  $handler  The cloned handler instance with request-specific state
+     * @param  self  $handler  The cloned handler instance with request-specific state
      * @return ResponseInterface The response
      */
     protected function executeSyncRequestWithCache(
@@ -282,7 +282,7 @@ protected function executeSyncRequestWithCache(
         array $options,
         float $startTime,
         ?array $cachedResult,
-        mixed $handler
+        self $handler
     ): ResponseInterface {
         try {
             $response = $handler->executeSyncRequest($method, $uri, $options, $startTime);