Statamic Asset Atlas Laravel Package

Technical Evaluation

Architecture fit
Statamic Asset Atlas is a Laravel/Statamic addon that overrides Statamic’s UpdateAssetReferences listener to use its own asset reference index (“Atlas”). This fits into Statamic’s event/listener architecture but replaces core behavior, creating tight coupling to Statamic internals. v0.6.3 fixes a correctness bug: the override previously skipped Statamic’s additional reference hook, so items supplied by that hook (e.g., working copies, drafts) retained stale asset paths after moves/renames/deletions. This matters for editorial workflows where drafts reference assets. The release also bumps the requirement to statamic/cms ^5.71, the first version exposing the additional hook, which is a hard compatibility constraint.

Integration feasibility
Installation is standard Composer (visuellverstehen/statamic-asset-atlas), with service provider auto-discovery typical of Statamic addons. Feasibility is moderate: the package is pre-1.0 (v0.6.3), so APIs and behavior may change. The override pattern requires validation that Atlas lookups remain equivalent to Statamic’s core lookups across all asset operations. Because the fix depends on a recent Statamic release, teams on older Statamic 5.x must upgrade Statamic first. Integration testing must cover asset moves, renames, and deletions with drafts and working copies, plus any custom code registered on the additional hook.

Technical risk

• Core override risk: Replacing a core listener means future Statamic updates can break reference tracking. The v0.6.3 fix shows the maintainers are tracking core changes, but each Statamic upgrade requires regression testing.
• Version lock: statamic/cms ^5.71 is a narrow constraint. Projects on earlier Statamic 5.x cannot upgrade the addon without first upgrading Statamic, which may pull in other breaking changes.
• Data integrity: The bug caused stale asset paths for drafts/working copies. Even though fixed, any gap in reference updating can produce broken links in previews or published content. Pre-1.0 status increases the chance of undiscovered edge cases.
• Pre-1.0 stability: Expect possible breaking changes in minor releases; pin versions and review changelogs.

Key questions

• Does the addon provide a backfill or repair command for references that were already stale before upgrading to v0.6.3?
• How does the Atlas index perform with large asset libraries (10k+ assets) and high reference counts?
• Are there other Statamic core listeners or hooks the override might bypass now or in future releases?
• What is the test coverage for asset operations across drafts, working copies, and multi-site setups?
• Is there a documented upgrade path from earlier 0.6.x versions, including any required cache/index rebuilds?
• How does the package interact with other addons that register on the additional hook?

Integration Approach

Stack fit
Requires Statamic CMS ^5.71 on Laravel (likely Laravel 10/11) and a supported PHP version (8.1+). Confirm the project’s Statamic version before adoption. The addon is suitable for teams that need reliable asset reference tracking and use Statamic’s drafts/working-copy workflows.

Migration path

1. Upgrade Statamic to at least 5.71 in a staging environment.
2. Install or upgrade statamic-asset-atlas to v0.6.3 via Composer.
3. Rebuild any Atlas index if the package provides a command (verify documentation).
4. Run targeted tests: move/rename/delete assets referenced by published content, drafts, and working copies; confirm references update correctly.
5. If stale references exist from prior versions, identify and repair them (re-save content, run a custom script, or use a package-provided repair command if available).
6. Deploy to production during a low-traffic window and monitor asset reference integrity.

Compatibility
The hard requirement on statamic/cms ^5.71 may conflict with other addons pinned to older Statamic versions. Run composer why-not statamic/cms 5.71 to surface conflicts. Because the package overrides a core listener, test against the exact Statamic version in use, including minor/patch releases. Pre-1.0 semver means minor version bumps may include breaking changes; pin to 0.6.3 and review each release.

Sequencing

• Phase 1 – Validation: In staging, upgrade Statamic, install v0.6.3, and test asset operations with drafts/working copies.
• Phase 2 – Remediation: Repair any existing stale references and document the process.
• Phase 3 – Controlled rollout: Enable the addon for a subset of assets or a single site (if multi-site) to monitor behavior.
• Phase 4 – Full rollout: Expand to all assets and content, with monitoring for broken links or stale references.
• Phase 5 – Ongoing: Add a regression test to CI that exercises asset moves/renames/deletions with drafts, and re-run after every Statamic or addon upgrade.

Operational Impact

Maintenance
Pre-1.0 package with an active maintainer (visuellverstehen). Expect frequent releases. Because it overrides core behavior, every Statamic upgrade requires a regression test pass on asset reference updates. Budget time for changelog review and staging validation. Keep the package pinned and avoid automatic minor upgrades without testing.

Support
Community-supported open-source addon; no commercial SLA. Check GitHub issues and release cadence. Have a contingency plan: either fork the package or implement a fallback reference-update mechanism if maintenance stalls. The override is small enough that a fork may be feasible, but requires Statamic internals knowledge.

Scaling
Performance depends on Atlas lookup efficiency versus Statamic’s core lookup. Test with production-scale asset libraries and reference volumes. The additional hook execution adds minor overhead during asset operations. If the Atlas index is not optimized, moves/deletions on heavily referenced assets could slow down. Monitor query counts and response times during asset operations, especially bulk moves.

Failure modes

• Stale references: If Atlas lookups miss items (e.g., future core hooks not supported), drafts or published content may retain old asset paths. Mitigate with automated link checking and regression tests.
• Composer failure: Version constraint mismatch blocks installation or upgrade. This is a hard fail at build time, which is safer than runtime failure but requires coordinated upgrades.
• Override drift: Statamic changes the UpdateAssetReferences listener in a future release; the addon’s override may silently skip new behavior. Monitor Statamic changelogs and test after each core upgrade.
• Index corruption: If the Atlas index becomes inconsistent, reference updates may fail. Ensure a rebuild command exists and document recovery steps.
• Pre-1.0 breaking changes: A minor upgrade could change behavior or configuration. Pin and review.

Ramp-up
Developers need familiarity with Statamic’s asset reference system and the additional hook. The package itself is small, so ramp-up is low for a Laravel/Statamic team. However, the override pattern requires understanding how Statamic registers and executes listeners. Allocate a short spike to read the addon source, confirm the override registration, and write an integration test. Editorial teams should be briefed that drafts and working copies now receive updated asset paths after moves—this is a positive workflow change but may alter preview behavior.