README

Create Dub short links for your entries.

Requirements

A Dub account (affiliate link) and API key. Learn more.
Craft CMS 5.0.0 or later.
PHP 8.2 or later.

Installation

To install the plugin, search for "Dub" in the Craft Plugin Store, or install manually using composer.

composer require bensomething/craft-dub

Then install the plugin via the Craft control panel under Settings → Plugins, or from the terminal:

php craft plugin/install dub

Configuration

Go to Settings → Plugins → Dub Links in the Craft control panel.
On the General tab, enter your Dub API key. You can use an environment variable (e.g. $DUB_API_KEY).
After saving your API key, the Domain field will suggest your available domains. Pick one, or use an environment variable (e.g. $DUB_DOMAIN).
In the Sections field, choose which sections to enable short links for. Leave All selected to enable every section that has URLs.
On the Sidebar tab, choose how the QR code appears in the entry sidebar (None, Icon, or Full), set its style (size, margin, foreground/background colour), and choose whether to Show click count.

Checking it works

The General tab has a Test button, and there is a console equivalent:

php craft dub/test

Both create a short link, read it back, fetch its QR code and delete it again, reporting each step. The write matters: an API key with no write scope, or a workspace at its link limit, passes every read and then fails the first time an editor saves an entry.

Domains per site

The General tab also lists every site that has its own base URL, so each can have its own short link domain. Sites without one are left out, since their entries have no URLs to shorten, and the list only appears when more than one site qualifies. Leave a site blank and it uses the Domain above, and so does one set to an environment variable that isn't defined in the current environment. Each field suggests your Dub domains and accepts an environment variable, exactly like the main one.

This only affects links created or updated from then on. An existing link keeps the domain it was created on until its entry is next saved, so after changing a site's domain run:

php craft resave/entries

php craft dub/check reports the links still on the old domain as stale in the meantime, so you can see what is left to move.

Setting enabled sections via environment

You can override the Sections selection with the DUB_SECTIONS environment variable, a comma-separated list of section handles:

DUB_SECTIONS=festivals,crew

When set, it takes precedence over the control panel selection (which is shown as read-only in the settings).

Usage

Once configured, a Short Link panel will appear in the sidebar of any entry that belongs to a section with URLs.

Creating a short link: enter a custom slug in the Short Link sidebar section and save the entry. If left blank, no short link is created.
Updating a short link: update the short link slug in the sidebar and save. The existing Dub link is updated in place.
Deleting a short link: a short link will be removed from Dub when an entry is deleted or when a short link slug is removed and the entry is saved.
Archiving a short link: a short link will be archived in Dub when an entry is disabled.
QR code: depending on the Sidebar → QR code setting, a QR code for the short link is shown in the sidebar as a small icon or a full image.
Click count: enable Sidebar → Show click count to display a read-only click total for the short link in the sidebar.

The entries index

The entries index can show a Short Link column. Open Customize sources from the gear at the bottom of the index sidebar, choose a source, and add Short Link to its Table Columns.

It is off by default, since the index belongs to whoever set it up. Each row shows the short link for the site being viewed, and nothing for an entry that has none. The column only appears for users with the View the Short Link panel permission.

Adopting existing 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/"

Checking existing links

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.

From the control panel

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.

Permissions

Two permissions appear under Settings → Users → Permissions, in a Dub Links group:

View the Short Link panel shows it in the entry sidebar.
Edit the short link slug is nested under it.

Without the second, the slug is shown but not editable, and a posted slug is ignored rather than applied. Links still follow their entries either way, so an editor without it saves normally and only loses the ability to rename or remove.

The Short Link column on the entries index follows the first permission. The Dub Links utility has its own checkbox under Utilities on the same screen, and its Repair links button additionally needs Edit the short link slug, so it is hidden without it.

Templating

Use the dubLink(entry) Twig function to output a short link in your templates:

{% set shortLink = dubLink(entry) %}
{% if shortLink %}
    <a href="{{ shortLink }}">{{ shortLink }}</a>
{% endif %}

Use the dubQr(entry) Twig function to output the short link's QR code image:

{% set qr = dubQr(entry) %}
{% if qr %}
    <img src="{{ qr }}" alt="QR code">
{% endif %}

bensomething / craft-dub

Maintainers

Package info

Statistics

Security