Statamic Smartlinks Laravel Package

Getting Started

• Publish/verify the config first: config/smartlinks.php. The key you care about in v0.2.1 is routes.segments, which maps each collection to a URL segment. The default layout is songs at /hoeren/song/{slug} and releases at /hoeren/release/{slug}.
• Check the route registration order and the collection order in that config file before you touch any URL. Slug lookups are scoped to a segment and then evaluated across the collections in config order — that ordering is now functional, not cosmetic.
• First use case: a "listen" / smartlink page per song and per release. Render links via landingUrl() and clickUrl() (or the package's Blade tags) rather than hand-building route() calls — that is the whole point of the v0.2.1 fix, since each entry now resolves its own route.
• Then run php artisan smartlinks:resolve once to populate platform links, and inspect the resulting statuses (dead, suspect, unknown) in the DB/CP before wiring up any scheduled job.

Implementation Patterns

• Never concatenate smartlink URLs by hand. Use landingUrl() for the public page and clickUrl() for the outbound redirect target. Treat these as the only supported way to get an entry's URL; the CP build and tags use the same path, so hand-built strings are the first thing to break on upgrade.
• Treat collections as URL namespaces. If you add a new collection, give it its own segment in routes.segments instead of relying on flat /{slug} routes. This is now the supported way to have a song and a release with the same slug.
• Resolution as a two-pass workflow. Schedule plain smartlinks:resolve for the routine sweep (it now counts every stored platform as present, dead or not, so it won't append a duplicate link next to a hidden dead one). Schedule a second, less frequent run with --replace-dead to actually repair dead rows.
• Replacement is in-place, not append. --replace-dead writes the newly found link into the dead link's row and preserves the other columns, so downstream code reading platform_id / entry_id doesn't change — only the URL and check history do.
• Keep the resolution log. Each replacement is logged; if you need an audit trail of "where did this link used to point", that log is your only source once --replace-dead drops the check history.
• Config order as routing. When two collections share a segment, the first collection in config order wins the lookup. Document that in your project so a reorder in config/smartlinks.php isn't mistaken for a no-op refactor.
• Test with slugs, not IDs. Feature-test /hoeren/song/{slug} and /hoeren/release/{slug} against a fixture that deliberately collides the same slug across both collections — that is the exact regression v0.2.1 exists to prevent.

Gotchas and Tips

• Song URLs are unchanged, release URLs are not. If you previously relied on a flat /hoeren/{slug} for releases, that is a silent 404 for existing traffic. Add 301 redirects from the old path before deploying, and grep your Blade/JS for hardcoded release URLs.
• --replace-dead is conservative by design. Only platforms whose links are all confirmed dead are re-resolved. suspect and unknown links are never touched — if a link is stuck in suspect, re-running the command will not help; you need to resolve its status first.
• Check history loss is irreversible. The command drops the replaced row's check history. If you have reporting on link health over time, snapshot it before the first --replace-dead run.
• No duplicate-appending anymore. Pre-v0.2.1 behaviour appended a second link beside a hidden dead one; the current command does not. If you built tooling that assumed "latest row = newest link", re-check it against the in-place replacement semantics.
• Debugging a wrong lookup: confirm (a) the segment in routes.segments, (b) the collection order in config, and (c) whether the entry is hidden/dead, in that order. Most "wrong page" reports are config order, not code.
• Extension points: landingUrl() / clickUrl() and the tags are the seam to override if you need signed or UTM-tagged outbound links — do it there rather than in a route macro, so the CP build stays consistent with the front end.