Statamic Asset Atlas Laravel Package

Product Decisions This Supports

• Build vs. buy for asset-heavy sites: Asset Atlas is a drop-in replacement for Statamic's core asset item lookup with an indexed ("atlas") lookup, aimed at sites where moving, renaming or deleting an asset is slow or times out. This release reinforces that it is a behavioral replacement, not just a read-side accelerator — it sits in the write path of UpdateAssetReferences, which is exactly the code that rewrites content when assets change.
• Content-integrity as a release gate: v0.6.3 fixes a real data bug — items surfaced through Statamic's additional reference hook (working copies and drafts, i.e. unpublished editorial work) were not having their asset paths rewritten on move/rename. For a PM this is the strongest argument to treat "asset reference rewriting" as a first-class quality area with regression tests across content states (published, draft, working copy), not just live entries.
• Upgrade sequencing / dependency roadmap: the fix requires statamic/cms ^5.71 — the first release exposing the additional hook. Adopting v0.6.3 therefore pins your minimum Statamic version, which becomes a line item in your upgrade plan and a constraint on any other addon you run.
• Use cases to prioritize: large or remotely-stored asset libraries (S3/CloudFront, DAM-backed containers), multi-site installs with heavy asset reuse, and editorial teams that rename assets often. These are the scenarios where core Statamic's reference update becomes a UX bottleneck (long saves, gateway timeouts) and where Atlas pays for itself.
• Vendor-risk tracking: the release shows the package overriding a core Statamic listener, with hooks deliberately left registered on Statamic's own listener class. That is a tight coupling to framework internals; each Statamic minor release is a potential breakage, which should inform how much of your asset pipeline you let depend on it.

When to Consider This Package

Consider it when:

• Asset moves/renames/deletes in the Control Panel are measurably slow, time out, or fail on large containers, and profiling points at reference-update scans rather than storage I/O.
• You run a remote filesystem (S3, R2, Bunny, etc.) where listing is expensive and an indexed lookup replaces repeated container scans.
• You are on, or willing to move to, Statamic 5.71+ — v0.6.3 hard-requires statamic/cms ^5.71, and earlier Statamic versions won't resolve.
• Your editorial workflow uses drafts and working copies (multi-site or revision-heavy setups). Before v0.6.3 those items silently kept stale asset paths; on v0.6.3 that gap is closed, so this release is effectively the first version safe for draft-based workflows.
• You can absorb pre-1.0 churn: the package is at 0.6.x, so minor bumps may carry behavior or requirement changes without a major-version signal.

Look elsewhere (or wait) when:

• Your asset library is small enough that core Statamic reference updates are already fast — the added coupling buys you nothing.
• You are pinned below Statamic 5.71 and cannot upgrade in this cycle; v0.6.3 is unavailable to you and v0.6.2 leaves drafts/working copies with stale paths.
• You depend on a supported, contract-stable API surface (SLA, long-term support, or vendor indemnity) — this is a single-maintainer addon that patches framework internals.
• Your asset lifecycle is managed outside Statamic (a DAM that owns renames) and reference rewriting isn't triggered from the Control Panel.

How to Pitch It (Stakeholders)

To executives: One paragraph. We can make asset management in the CMS fast and reliable for a library of our size without building or buying a separate digital asset manager. The trade-off is dependency: this addon hooks into internals of Statamic, so we must keep our CMS version current — the newest release already requires Statamic 5.71 minimum. It's low cost, low lock-in (uninstall restores core behavior), and it removes a known editorial pain point: renames that leave broken images. Recommend: adopt on asset-heavy sites only, track vendor risk each Statamic upgrade.

To engineering: This release fixes reference propagation for items returned by Statamic's additional hook — the Atlas override of UpdateAssetReferences had replaced core item lookup and skipped the hook, so working copies and drafts kept old asset paths after a move. Hooks remain registered on Statamic's listener class. Cost of adoption: a minimum-version bump to statamic/cms ^5.71, and a standing requirement to regression-test asset move/rename/delete across published, draft and working-copy states on every Statamic minor. Package is pre-1.0; pin exact versions and read changelogs. Action: upgrade to v0.6.3 and 5.71 together, and add a smoke test for move/rename on a draft to prevent a repeat.