feat: Implement dynamic tagging for API cache with enhanced cache invalidation logic

Author: renatomarinho

.github/workflows/tests.yml

@@ -47,14 +47,13 @@ jobs:
 
             - name: Install dependencies
               run: |
-                  composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
-                  composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction
+                  COMPOSER_MEMORY_LIMIT=-1 composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction --with="laravel/framework:${{ matrix.laravel }}" --with="orchestra/testbench:${{ matrix.testbench }}"
 
             - name: List Installed Dependencies
               run: composer show -D
 
             - name: Execute tests
-              run: vendor/bin/phpunit
+              run: php -d memory_limit=512M vendor/bin/phpunit
 
             - name: Check code style
               run: vendor/bin/phpcs -p --standard=PSR2 --runtime-set ignore_errors_on_exit 1 --runtime-set ignore_warnings_on_exit 1 src tests

composer.json

@@ -49,4 +49,4 @@
             ]
         }
     }
-}
+}

config/laravel-page-speed.php

@@ -131,6 +131,12 @@
                 'application/vnd.api+json',
             ],
             'purge_methods' => ['POST', 'PUT', 'PATCH', 'DELETE'], // HTTP verbs that invalidate cached GETs
+            'dynamic_tagging' => [
+                'enabled' => env('API_CACHE_DYNAMIC_TAGS', true),
+                'ignore_segments' => ['api'],
+                'normalize_ids' => true,
+                'max_depth' => 5,
+            ],
         ],
 
         /*

src/Middleware/ApiResponseCache.php

@@ -5,6 +5,7 @@
 use Closure;
 use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
 
 /**
  * API Response Cache Middleware
@@ -267,12 +268,17 @@ protected function indexCacheKey($store, $cacheKey, array $tags, $ttl)
         }
 
         try {
-            $indexKey = $this->getTagIndexKey($tags);
-            $keys = $store->get($indexKey, []);
-            $keys[$cacheKey] = now()->addSeconds($ttl)->getTimestamp();
+            $expiry = now()->addSeconds($ttl)->getTimestamp();
+            $indexTtl = max($ttl, 600);
 
-            // Keep index fresh slightly longer than cache TTL to ensure cleanup
-            $store->put($indexKey, $keys, max($ttl, 600));
+            foreach (array_unique($tags) as $tag) {
+                $indexKey = $this->getTagStorageKey($tag);
+                $entries = $store->get($indexKey, []);
+                $entries = $this->pruneExpiredIndexEntries($entries);
+                $entries[$cacheKey] = $expiry;
+
+                $store->put($indexKey, $entries, $indexTtl);
+            }
         } catch (\Exception $e) {
             Log::debug('API cache index write failed', [
                 'key' => $cacheKey,
@@ -291,42 +297,66 @@ protected function indexCacheKey($store, $cacheKey, array $tags, $ttl)
      */
     protected function flushIndexedKeys($store, array $tags)
     {
+        $invalidated = false;
+
         try {
-            $indexKey = $this->getTagIndexKey($tags);
-            $keys = $store->get($indexKey, []);
+            foreach (array_unique($tags) as $tag) {
+                $indexKey = $this->getTagStorageKey($tag);
+                $entries = $store->get($indexKey, []);
 
-            if (empty($keys)) {
-                return false;
-            }
+                if (empty($entries)) {
+                    continue;
+                }
 
-            foreach (array_keys($keys) as $cacheKey) {
-                $store->forget($cacheKey);
-            }
+                foreach (array_keys($entries) as $cacheKey) {
+                    $store->forget($cacheKey);
+                }
 
-            $store->forget($indexKey);
-
-            return true;
+                $store->forget($indexKey);
+                $invalidated = true;
+            }
         } catch (\Exception $e) {
             Log::debug('API cache index flush failed', [
                 'tags' => $tags,
                 'error' => $e->getMessage(),
             ]);
         }
 
-        return false;
+        return $invalidated;
     }
 
     /**
-     * Build deterministic index key for a given tag list.
+     * Build deterministic storage key for a given tag.
      *
-     * @param  array $tags
+     * @param  string $tag
      * @return string
      */
-    protected function getTagIndexKey(array $tags)
+    protected function getTagStorageKey($tag)
     {
-        sort($tags);
+        return self::CACHE_PREFIX . 'tag_index:' . md5($tag);
+    }
 
-        return self::CACHE_PREFIX . 'tag_index:' . md5(implode('|', $tags));
+    /**
+     * Remove expired cache key references from the index.
+     *
+     * @param  array $entries
+     * @return array
+     */
+    protected function pruneExpiredIndexEntries(array $entries)
+    {
+        if (empty($entries)) {
+            return $entries;
+        }
+
+        $now = now()->getTimestamp();
+
+        foreach ($entries as $cacheKey => $timestamp) {
+            if ($timestamp <= $now) {
+                unset($entries[$cacheKey]);
+            }
+        }
+
+        return $entries;
     }
 
     /**
@@ -415,29 +445,160 @@ protected function getCacheTags($request)
     {
         $tags = [];
 
-        // Add route-based tag
         $route = $request->route();
         if ($route && $route->getName()) {
             $tags[] = 'route:' . $route->getName();
         }
 
-        // Add path-based tag
-        $pathSegments = explode('/', trim($request->path(), '/'));
-        if (! empty($pathSegments[0])) {
-            $tags[] = 'path:' . $pathSegments[0];
-        }
+        $tags = array_merge($tags, $this->buildDynamicPathTags($request));
 
-        // Add custom tags from route
         if ($route) {
             $customTags = $route->getAction('cache_tags');
             if (is_array($customTags)) {
                 $tags = array_merge($tags, $customTags);
             }
         }
 
+        $tags = array_values(array_unique(array_filter($tags)));
+
         return $tags;
     }
 
+    /**
+     * Build dynamic cache tags derived from the request path.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return array
+     */
+    protected function buildDynamicPathTags($request)
+    {
+        if (! config('laravel-page-speed.api.cache.dynamic_tagging.enabled', true)) {
+            $fallbackSegment = Str::lower(trim($request->segment(1)));
+
+            return $fallbackSegment ? ['path:' . $fallbackSegment] : [];
+        }
+
+        $segments = $this->getRelevantSegments($request);
+
+        if (empty($segments)) {
+            return [];
+        }
+
+        $maxDepth = (int) config('laravel-page-speed.api.cache.dynamic_tagging.max_depth', 5);
+        if ($maxDepth > 0) {
+            $segments = array_slice($segments, 0, $maxDepth);
+        }
+
+        $tags = [];
+
+        // Preserve compatibility with legacy path tag
+        $tags[] = 'path:' . $segments[0];
+        $tags[] = 'collection:' . $segments[0];
+
+        // Cumulative tags with raw segments
+        $cumulative = [];
+        foreach ($segments as $segment) {
+            $cumulative[] = $segment;
+            $tags[] = 'resource:' . implode(':', $cumulative);
+        }
+
+        $normalizedSegments = $this->normalizeSegments($segments);
+        $normalizedCumulative = [];
+        foreach ($normalizedSegments as $segment) {
+            $normalizedCumulative[] = $segment;
+            $tags[] = 'resource:' . implode(':', $normalizedCumulative);
+        }
+
+        $tags[] = 'fqn:' . implode('/', $segments);
+        $tags[] = 'fqn:' . implode('/', $normalizedSegments);
+
+        return array_values(array_unique($tags));
+    }
+
+    /**
+     * Filter request segments to relevant portions for tagging.
+     *
+     * @param  \Illuminate\Http\Request $request
+     * @return array
+     */
+    protected function getRelevantSegments($request)
+    {
+        $segments = array_values(array_filter(explode('/', trim($request->path(), '/')), 'strlen'));
+
+        if (empty($segments)) {
+            return [];
+        }
+
+        $ignore = array_map('strtolower', config('laravel-page-speed.api.cache.dynamic_tagging.ignore_segments', ['api']));
+
+        $segments = array_values(array_filter($segments, function ($segment) use ($ignore) {
+            return ! in_array(strtolower($segment), $ignore, true);
+        }));
+
+        return array_map(function ($segment) {
+            return Str::lower($segment);
+        }, $segments);
+    }
+
+    /**
+     * Normalize path segments by replacing identifiers with placeholders when enabled.
+     *
+     * @param  array $segments
+     * @return array
+     */
+    protected function normalizeSegments(array $segments)
+    {
+        if (! config('laravel-page-speed.api.cache.dynamic_tagging.normalize_ids', true)) {
+            return $segments;
+        }
+
+        return array_map(function ($segment) {
+            return $this->normalizeSegment($segment);
+        }, $segments);
+    }
+
+    /**
+     * Normalize a single segment.
+     *
+     * @param  string $segment
+     * @return string
+     */
+    protected function normalizeSegment($segment)
+    {
+        return $this->isIdentifierSegment($segment) ? '{id}' : $segment;
+    }
+
+    /**
+     * Determine if the segment represents an identifier.
+     *
+     * @param  string $segment
+     * @return bool
+     */
+    protected function isIdentifierSegment($segment)
+    {
+        if ($segment === '') {
+            return false;
+        }
+
+        if (preg_match('/^\d+$/', $segment)) {
+            return true;
+        }
+
+        if (preg_match('/^[0-9a-f]{24}$/i', $segment) || preg_match('/^[0-9a-f]{32}$/i', $segment) || preg_match('/^[0-9a-f]{40}$/i', $segment)) {
+            return true;
+        }
+
+        if (preg_match('/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i', $segment)) {
+            return true;
+        }
+
+        if (preg_match('/^[0-9A-HJKMNP-TV-Z]{26}$/', strtoupper($segment))) { // ULID support
+            return true;
+        }
+
+        return false;
+    }
+
     /**
      * Determine if the request should be cached.
      *