Statamic Clear Assets Laravel Package

Getting Started

1. Install and confirm compatibility. composer require swiftmade/statamic-clear-assets — v3.4.0 is the first release advertising Laravel 13.x support, so on a Laravel 12 app you can bump freely, but check composer show swiftmade/statamic-clear-assets afterwards to see the exact illuminate/* and statamic/cms constraints it resolved against. The Laravel 13 bump also raises the practical PHP floor, so verify your runtime before rolling this out to older servers.
2. Nothing to register by hand. Like most Statamic addons, it is discovered via the extra.statamic block in its composer.json; the service provider boots automatically. If you are on a cached-manifest setup, run php artisan package:discover (or a full composer install) after upgrading.
3. Find the entry point. Run php artisan list and grep for asset — the addon's command(s) will show up there. Reading vendor/swiftmade/statamic-clear-assets/src/ (service provider + command class) takes two minutes and tells you exactly which cache directory/handler is being purged.
4. First real use case: you deploy asset files by rsync/git rather than through the Control Panel, the CP asset browser keeps showing stale metadata (old dimensions, missing files, wrong timestamps). Run the addon's clear command, reload the asset container in the CP, and the data is re-read from disk. That single workflow is 90% of the package's day-to-day value.

Implementation Patterns

Deployment hook (the canonical use). Wire the command into your deploy script after the new release is symlinked live and after config:cache / route:cache, but before you hit the site with a smoke test:

php artisan migrate --force
php artisan config:cache
php artisan statamic:stache:clear
php artisan <addon-clear-command>

Deployer, Envoyer, Laravel Forge deploy scripts and GitHub Actions all take this the same way — one extra line in the after / post-deploy phase.

Local development. Whenever you add, rename or delete files in an asset container outside the CP (drag-and-drop in Finder, git checkout of a branch that touches public/assets), run the clear command instead of hunting through the CP's per-asset "update" button.

Chain it into an existing "cache bust" command. Most teams already have a app:clear-caches or similar. Compose the addon's command inside it with $this->call(...) so nobody has to remember the addon-specific name:

Artisan::call('cache:clear');
Artisan::call('view:clear');
Artisan::call('<addon-clear-command>');

Scheduled refresh. If assets are pushed in by an external sync (CDN pull, S3 mirror, editorial export), schedule the clear command in routes/console.php / the scheduler at a low frequency rather than clearing on every request.

Pair with Glide. For image-heavy sites the pattern that actually holds up is: clear asset metadata → clear Glide cache → warm. Keep each step as a separate command so a failure in one doesn't silently swallow the others.

Gotchas and Tips

• It does not clear everything. Asset metadata is a different cache from the Stache, the view cache, the application cache and the Glide image cache. If thumbnails still look wrong after running this, you want php artisan glide:clear; if entries look stale, you want statamic:stache:clear. Reaching for cache:clear first is the classic time-waster here.
• Clearing is not re-indexing. The cache is rebuilt lazily on the next request that touches the container. Expect the first CP asset-browser load after a deploy to be measurably slower on containers with thousands of files — that is normal, not a broken deploy.
• Permission failures are silent-ish. The command runs as the deploy user; if storage/ is owned by www-data (or vice versa), you get a partial or failed purge. Verify ownership after a fresh provision, and run the command as the same user the web server uses when in doubt.
• Version pinning across environments. v3.4.0's headline change is the Laravel 13 constraint widening. If your CI matrix still tests Laravel 11/12, pin ^3.3 there or confirm the constraint still covers your floor — a widened upper bound does not always mean the lower bound is unchanged.
• This is not a breaking release. v3.4.0 is a compatibility release plus a new contributor; there are no deprecations or behavioural changes to migrate. Treat it as a routine patch and read the diff if you are unusually cautious.
• Debugging: run the command with -v and check the storage/ path it reports. If nothing appears to change, confirm you are not looking at a CDN/browser cache — the CP is a SPA and will happily serve cached JSON.
• Extension point: because it is just an artisan command, wrap it in your own App\Console\Commands if you need to add logging, Slack notifications or environment guards (e.g. skip on production during business hours). No need to fork the addon for that.