Adopting & Checking Links

If your Dub workspace already contains short links for your entries, created manually or before installing the plugin, you can hand them over to the plugin in one pass:

php craft dub/adopt

This scans your workspace, matches each link to a Craft entry by its destination URL, sets the entry's externalId on the link so the plugin manages it going forward, and records it locally. Matching uses the host and path together, so sites on separate domains or subdomains are told apart even when they share a path. Links are left untouched if no entry matches, or if two sites on the same host share the path.

Links it could not match are listed, capped at the first ten with a count of the rest. Pass --show-unmatched to see them all, which is worth doing on a workspace holding domains this install does not manage.

Add --dry-run to preview what would be adopted without making any changes:

php craft dub/adopt --dry-run

If some of your Dub links point to an old path prefix, use --rewrite to remap the destination path when matching. It only applies as a fallback, when the link's original path matches no entry. Pass one or more comma-separated from=to prefixes:

php craft dub/adopt --rewrite="/areas-stages/=/venues/"

Saving an entry doesn't re-send a short link that hasn't moved, which keeps a resave cheap. The trade-off is that the plugin won't notice if a link is deleted or edited in the Dub dashboard, leaving the entry sidebar showing a short link that no longer resolves.

To find those:

php craft dub/check

It reports three things, and exits non-zero if any of them turn up, so it can be run from cron or CI:

• missing, meaning the link has been deleted at Dub
• drifted, meaning its slug or destination was edited at Dub
• stale, meaning it no longer points where its entry lives

Add --fix to repair missing and drifted links:

php craft dub/check --fix

Each side keeps what it owns. The destination belongs to Craft, since it comes from the entry, so Craft's value is pushed back to Dub. The slug belongs to Dub, since renaming a link there is deliberate and the renamed URL is the one now in circulation, so the rename is adopted into Craft's record rather than reversed. A link that has gone from Dub entirely is recreated with the slug, destination and archived state Craft still holds. Its click history does not come back, because that went with the original link.

Stale links aren't repaired by --fix. A short link only moves when its entry is saved, so changing a site's Base URL or the Domain setting leaves existing links pointing at the old place. Nothing is wrong at Dub, and the repair is an ordinary resave:

php craft resave/entries

Since a save no longer re-sends a link that hasn't moved, that sends one request per link that has actually changed and nothing for the rest.

This is the counterpart to dub/adopt. Adoption brings links that exist at Dub under Craft's management, while dub/check looks the other way, at links Craft thinks it has.

The same check has a screen at Utilities → Dub Links, for the people who look after the links but have no terminal. It reports the same three findings, with each one named after its entry and linked to it, and Repair links does what --fix does.

It works through the links in batches, reporting each batch as it lands and counting up as it goes, so a large workspace takes a while rather than running out of time. A run that does fail partway leaves what it already found on screen.