|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Commands |
| 6 | + |
| 7 | +```bash |
| 8 | +# Run all tests |
| 9 | +vendor/bin/pest |
| 10 | + |
| 11 | +# Run a single test file |
| 12 | +vendor/bin/pest tests/Unit/TrackerTest.php |
| 13 | + |
| 14 | +# Run a specific test by name |
| 15 | +vendor/bin/pest --filter "test name" |
| 16 | + |
| 17 | +# Lint (Laravel Pint) |
| 18 | +vendor/bin/pint |
| 19 | + |
| 20 | +# Build CP assets |
| 21 | +npm run build |
| 22 | + |
| 23 | +# Dev CP assets |
| 24 | +npm run dev |
| 25 | +``` |
| 26 | + |
| 27 | +## Architecture |
| 28 | + |
| 29 | +This is a Statamic addon (`thoughtco/statamic-cache-tracker`) that tracks which content items are rendered on each page, then automatically clears those pages from the static cache when content is updated. |
| 30 | + |
| 31 | +### Core Flow |
| 32 | + |
| 33 | +1. **Tracking** — `Http/Middleware/CacheTracker` runs on every GET request. It hooks into Statamic's augmentation lifecycle (via `Asset::hook`, `Entry::hook`, `LocalizedTerm::hook`, etc.) to collect "tags" for each content item rendered during the request. After a successful response, it stores a `URL → [tags]` mapping in cache. |
| 34 | + |
| 35 | +2. **Invalidation** — `Listeners/Subscriber` subscribes to Statamic save/delete events (entries, assets, terms, navs, forms, globals). When content changes, it dispatches `Jobs/InvalidateTags` which calls `Tracker::invalidate($tags)` to find all URLs containing those tags and clear them from the static cache. |
| 36 | + |
| 37 | +3. **Tag format** — Tags follow patterns like `asset:{id}`, `collection:{handle}:{id}`, `term:{id}`, `form:{handle}`, `nav:{handle}`, `global:{handle}`. Wildcard matching is supported via `*` prefix notation (e.g., `collection:blog:*`). |
| 38 | + |
| 39 | +### Key Classes |
| 40 | + |
| 41 | +- **`Tracker/Manager`** — Core logic. Stores `URL → tags[]` in cache under key `tracker::urls`. Handles `add`, `get`, `invalidate`, and `flush`. Tag matching supports wildcards. |
| 42 | +- **`Http/Middleware/CacheTracker`** — Hooks into Statamic augmentation to collect tags during rendering. Also fires `TrackContentTags` event for custom integrations. |
| 43 | +- **`Listeners/Subscriber`** — Maps Statamic events to tag generation and queues invalidation. |
| 44 | +- **`Facades/Tracker`** — Facade for `Manager` (bound as `cache-tracker`). |
| 45 | + |
| 46 | +### Extending |
| 47 | + |
| 48 | +Custom tag sources can be registered via `Tracker::addAdditionalTracker()`, which accepts a closure or class with an `__invoke(Request $request, array &$tags)` signature and runs in a pipeline. |
| 49 | + |
| 50 | +The `TrackContentTags` event can be fired from custom code to inject additional tags into the current request's tracking. |
| 51 | + |
| 52 | +### CP Features |
| 53 | + |
| 54 | +- **Utility** — "Cache Tracker" utility in the CP for manually clearing URLs or wildcards. |
| 55 | +- **Bulk Actions** — "View Cache Tags" and "Clear Cache" actions available on entry/term listings. |
| 56 | +- **Permissions** — `view cache tracker tags` and `clear cache tracker tags`. |
| 57 | + |
| 58 | +### Testing Notes |
| 59 | + |
| 60 | +Tests use Pest with an `AddonTestCase` base that: |
| 61 | +- Enables static caching with `half` strategy |
| 62 | +- Creates a default `pages` collection with a `home` entry |
| 63 | +- Disables stache disk writes |
| 64 | +- Uses SQLite in-memory database |
| 65 | + |
| 66 | +Fixture views live in `tests/__fixtures__/resources/views/`. |
0 commit comments