Statamic Scheduled Cache Invalidator Laravel Package

Getting Started

Install via Composer: composer require mitydigital/statamic-scheduled-cache-invalidator. Publish the config and migrations: php artisan vendor:publish --tag="statamic-scheduled-cache-invalidator-config" and php artisan vendor:publish --tag="statamic-scheduled-cache-invalidator-migrations", then run php artisan migrate. Add the scheduler entry to app/Console/Kernel.php (or routes/console.php in Laravel 11+): $schedule->command('statamic:cache-invalidator:run')->everyMinute()->withoutOverlapping();. First use case: in the Statamic CP, add the “Scheduled Cache Invalidator” field to a collection or use the provided listing to schedule cache invalidation for an entry’s URL. Alternatively, create a record programmatically via the package’s Eloquent model (ScheduledCacheInvalidation) to schedule invalidation at a future timestamp.

Implementation Patterns

• Programmatic scheduling: Use the model directly to create invalidation records: ScheduledCacheInvalidation::create(['url' => $url, 'scheduled_at' => now()->addHour()]);. The model supports polymorphic relations (invalidatable_type, invalidatable_id) to tie invalidations to entries, terms, or assets.
• CP fieldtype: Add the field to blueprints for editor-friendly scheduling; the field stores the scheduled datetime and creates the corresponding record on save.
• Event-driven integration: Listen to Statamic events (e.g., EntrySaved, TermSaved) and conditionally schedule invalidations, e.g., when a future publish date is set.
• Manual invalidation: Use the package’s service or command to trigger invalidation immediately, useful for testing or admin actions.
• Multi-site: Ensure the url field contains the full domain (or use the package’s URL resolver) so that the correct site’s cache is cleared.
• Queue-friendly: The invalidation command can be queued; if you expect high volume, run the scheduler with onOneServer() and consider a dedicated queue.

Gotchas and Tips

• Cache driver support: The package relies on Laravel’s cache repository; tag-based invalidation requires a driver that supports tags (Redis, Memcached). File and database drivers do not support tags—use URL-based invalidation or switch drivers.
• Timezone: scheduled_at is stored in UTC by default; ensure APP_TIMEZONE is set correctly and that CP inputs are converted appropriately.
• 2.2.1 “Eloquent update” (PR #17): This patch likely adjusts the Eloquent model for compatibility with newer Laravel versions (e.g., casts, fillable, or relationship definitions). Run composer update and re-run migrations if you have custom model overrides; no breaking changes expected.
• Scheduler frequency: The command must run every minute to catch due invalidations. Use withoutOverlapping() to prevent concurrent runs, and ensure the scheduler is actually running (e.g., cron entry or schedule:work).
• Queue workers: If the invalidation job is queued, ensure workers are running; otherwise invalidations will not fire.
• Extension points: You can extend the model via config (model key) or override the command; publish the config to adjust table names, queue settings, or the invalidation strategy.
• Testing: Use Cache::shouldReceive('forget') or a fake cache driver in tests; the package’s command can be invoked directly in feature tests.