Statamic Smartlinks Laravel Package

Technical Evaluation

Scope note: no prior assessment exists and no repository/telemetry data was supplied; this evaluation is derived solely from the v0.2.1 release notes and must be re-validated against the codebase.

Architecture fit. The package owns the full smartlink lifecycle inside the Laravel application: collections (songs, releases, likely artist/other), per-platform stored links, a health-check history, configurable route segments (smartlinks.routes.segments), a console command (smartlinks:resolve), and URL builders (landingUrl(), clickUrl()) consumed by tags and a "CP build" (static/control-panel output). The fact that URL construction is centralised in two methods used consistently by tags and the build is the strongest architectural signal here — it means the route change is contained to a small number of call sites rather than scattered through templates. Config-driven per-collection segments are the right abstraction for a slug-collision problem and scale to future collections without further code changes. This is a small, opinionated, single-purpose package: low architectural surface, high coupling to its own config and command schedule.

Integration feasibility. Straightforward for a Laravel shop: composer install, publish/merge config, register routes, schedule smartlinks:resolve. The v0.2.1 work does not add new infrastructure dependencies. The only integration friction is URL-related, not code-related.

Technical risk.

• Route restructuring is a breaking change shipped in a patch release. Release URLs move to /hoeren/release/{slug} while song URLs are unchanged. Any external inbound link, sitemap entry, QR code, ad campaign, or persisted absolute URL stored in the database or baked into a previously generated CP build will 404 after deploy. No redirect or backfill is mentioned.
• Semver/expectation risk: consumers reasonably expect a 0.2.x patch to be drop-in. Treat this as a minor-with-migration, not a patch.
• Destructive data path: --replace-dead writes the newly found link into the dead link's row, drops that platform's check history, and preserves other columns. That is an irreversible audit-trail loss and an in-place mutation with no stated dry-run, transaction boundary, or rollback.
• Silent behaviour change in smartlinks:resolve: it now counts every stored platform as present whether dead or not, and no longer appends a duplicate next to a hidden dead link. Any downstream consumer counting rows or expecting the previous append-on-resolve pattern will see different results without any error.
• Config-order dependency: slug resolution is "each slug looked up only in its segment's collections, in config order." Correctness now depends on the ordering of an array in configuration — a subtle, environment-specific failure mode.

Key questions.

1. Are 301 redirects from the old release URL shape planned or shipped? If not, who owns them and when?
2. Are absolute URLs persisted anywhere (DB columns, sitemap, meta/OG tags, CP artifacts, CDN cache)? What is the backfill/regeneration plan?
3. What exactly qualifies a link as "confirmed dead" (HTTP status set, retry count, grace period) — and can a replacement be wrong (wrong region, wrong artist, re-issued link)?
4. Is --replace-dead transactional, idempotent, and runnable as a dry-run? Where do the replacement logs go and what is their retention?
5. Is dropping check history acceptable to compliance/product analytics, or should it be soft-deleted/archived instead?
6. Is smartlinks.routes.segments identical across all environments and is it covered by a deploy-time check?
7. What Laravel/PHP versions are supported, and is route caching (route:cache) part of the deploy pipeline?

Integration Approach

Stack fit. Assumes a standard Laravel app with config publishing, route registration via a service provider, an artisan command on the scheduler, and a build step ("CP build") that consumes package-generated URLs. Nothing in v0.2.1 changes that shape; the package remains a drop-in composer dependency.

Migration path. This release requires an explicit migration, not a composer update:

1. Add/verify the smartlinks.routes.segments map (song segment unchanged, release segment new).
2. Audit data for cross-collection slug collisions to confirm the fix actually applies to real rows.
3. Add 301 redirects from old release URLs to /hoeren/release/{slug} at the web-server or route level.
4. Backfill or regenerate any persisted or cached absolute URLs (DB, sitemap, OG/meta, CDN, previously built CP output).
5. Rebuild route/config/view caches and re-run the CP build.

Compatibility. Song URLs are explicitly unchanged, which bounds the blast radius to releases. suspect/unknown links are explicitly never touched by --replace-dead, which is a sensible safety boundary. The unconditional change to smartlinks:resolve counting semantics is the main compatibility caveat and has no opt-out flag — verify every consumer of the link table before enabling.

Sequencing. Deploy code + config → clear and rebuild route caches → verify new URL shapes via landingUrl()/clickUrl() smoke tests → land redirects before traffic hits the new build → regenerate CP artifacts and tags → run --replace-dead manually in a low-traffic window with a DB snapshot → only then add the flag to the scheduled run. Redirects and artifact regeneration must not be deferred to a follow-up ticket.

Operational Impact

Maintenance. Low ongoing code maintenance; the recurring cost is configuration ownership. smartlinks.routes.segments and its collection ordering become production-critical config that must be reviewed like code and diffed across environments. Budget for a documented runbook covering the URL scheme and the dead-link replacement policy.

Support. Expect a short-term spike in inbound 404 reports, broken-campaign reports, and SEO/analytics anomalies immediately after deploy. Content ops will need a one-page explainer on the new release URL shape and on why some platform links get replaced. The replacement log is the first place support will look — make sure it is queryable and retained.

Scaling. smartlinks:resolve now processes every stored platform each run regardless of dead status, so per-run work grows monotonically with catalogue size rather than with the number of dead links. This is fine today but should be watched: runtime, outbound request volume, and third-party platform rate limits are the likely ceilings. If the catalogue grows, expect to need batching or filtering flags in a later release.

Failure modes.

• 404 storm / lost SEO equity from the release route change if redirects and artifact regeneration lag the deploy.
• Wrong-entity routing if the segments collection ordering is misconfigured — the lookup succeeds silently against the wrong collection rather than erroring.
• Irreversible audit loss from --replace-dead dropping check history with no stated rollback; a bad replacement also silently overwrites a row while keeping unrelated columns, so the record can look internally inconsistent.
• Silent semantic drift in smartlinks:resolve for any dashboard or export that counts stored platforms.
• Stale route cache in environments that cache routes and skip a rebuild.

Ramp-up. Low for a Laravel developer — one config file, one command, two URL helpers. Medium for content/ops staff, who must absorb both the new URL scheme and the dead-link replacement semantics. Recommend a half-day of engineering time for the migration and a short written handover for ops before the release is promoted beyond staging.