Hierarchical cache tags and automatic invalidation on mutations

Mutating methods invalidate the request path at the HttpClient level.
Cache entries are tagged hierarchically so parent path invalidation
cascades to children.

Author: eluhr

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [1.1.1] - 2026-03-26
+
+### Changed
+- Mutating methods (POST, PATCH, DELETE) in `HttpClient` now automatically invalidate
+  the cache for the request path
+- Cache entries use hierarchical `TagDependency` tags — invalidating a parent path
+  (e.g. `/posts`) also clears all child entries (e.g. `/posts/1`)
+- `Resource::$cacheInvalidationPaths` now only handles cross-resource invalidation;
+  per-path invalidation is handled by `HttpClient`
+
 ## [1.1.0] - 2026-03-26
 
 ### Fixed

README.md

@@ -333,9 +333,11 @@ and `cacheDuration` is greater than 0. Cache keys include both the request path
 parameters, so requests to the same endpoint with different parameters (e.g. `?expand=comments`
 vs. no expand) are cached independently.
 
-Mutating operations (POST, PATCH, DELETE) in resources can invalidate related cache entries
-through the `$cacheInvalidationPaths` property. Invalidation uses Yii2's `TagDependency` to
-clear **all** parameter variants of a path at once.
+Mutating operations (POST, PATCH, DELETE) automatically invalidate the cache for the
+request path. Cache entries are tagged hierarchically, so invalidating a parent path
+(e.g. `/posts`) also clears all child entries (e.g. `/posts/1`).
+
+Resources can define additional paths to invalidate via `$cacheInvalidationPaths`:
 
 ```php
 class PostResource extends Resource

src/HttpClient.php

@@ -158,7 +158,7 @@ public function get(string $path, array $options = []): array
                 $cacheKey,
                 $data,
                 $this->cacheDuration,
-                new TagDependency(['tags' => [$this->getCacheTag($path)]])
+                new TagDependency(['tags' => $this->getCacheTags($path)])
             );
         }
 
@@ -168,17 +168,21 @@ public function get(string $path, array $options = []): array
     public function patch(string $path, array $options): true
     {
         $this->sendRequest('PATCH', $path, $options);
+        $this->invalidateCache($path);
         return true;
     }
 
     public function post(string $path, array $options): array
     {
-        return $this->sendRequest('POST', $path, $options);
+        $data = $this->sendRequest('POST', $path, $options);
+        $this->invalidateCache($path);
+        return $data;
     }
 
     public function delete(string $path, array $options = []): true
     {
         $this->sendRequest('DELETE', $path, $options);
+        $this->invalidateCache($path);
         return true;
     }
 

src/traits/CacheInvalidation.php

@@ -32,6 +32,23 @@ public function getCacheTag(string $path): string
         return 'httpclient:tag:' . md5(rtrim($this->baseUri, '/') . '/' . ltrim($path, '/'));
     }
 
+    /**
+     * Generate hierarchical cache tags for a path.
+     * Returns tags for the path and all parent paths, so invalidating
+     * a parent (e.g. /person) also clears children (e.g. /person/123).
+     */
+    public function getCacheTags(string $path): array
+    {
+        $segments = explode('/', trim($path, '/'));
+        $tags = [];
+        $current = '';
+        foreach ($segments as $segment) {
+            $current .= ($current ? '/' : '') . $segment;
+            $tags[] = $this->getCacheTag($current);
+        }
+        return $tags;
+    }
+
     /**
      * Invalidate all cached variants for a specific path
      */