Configuration¶
Settings¶
Navigate to Administration > Configuration > System > Short URL
(/admin/config/shorturl/settings) to configure the module.
Base36 slug length¶
The number of characters in randomly generated base36 slugs. Accepts values from 4 to 12 (default: 6). A 6-character base36 slug provides over 2 billion possible combinations.
Default redirect status code¶
The HTTP status code a new short URL starts with. Options:
| Code | Meaning | Use case |
|---|---|---|
| 301 | Moved Permanently | SEO-friendly, browsers cache it |
| 302 | Found | Temporary redirect |
| 307 | Temporary Redirect | Preserves HTTP method |
Default: 301.
Each short URL keeps its code in its own Redirect status field, so changing this setting leaves existing short URLs as they are.
Destination type¶
Controls what types of URLs can be used as destinations:
- Both (default) — internal entity references and external URLs
- External only — only full external URLs (e.g.
https://example.com), enforced when a short URL is validated (node form, REST, JSON:API)
QR code format¶
The default format for QR code images served at
/api/shorturl/qr/{slug}:
- PNG (default) — raster image, universally compatible
- SVG — vector image, scales without quality loss
Administration theme for short URL pages¶
When enabled, a short URL's page, with its QR code and its image links, and the pages of its revisions use the administration theme for users with the View the administration theme permission, like its Edit and Statistics tabs. Other users see them in the front-end theme.
Default: on for new installs. Sites updated from an earlier version keep the front-end theme until they turn it on.
Visit tracking¶
When enabled, the module records every redirect hit in the
shorturl_visits database table via a lightweight HTTP middleware.
Disabling this removes the middleware entirely for zero overhead.
Browser cache control (no-store)¶
When enabled, redirects include a Cache-Control: no-store header
that prevents browsers from caching the redirect response. This
ensures every visit is recorded by the middleware. Disable this if
you prefer faster redirects at the cost of potentially missed
visits.
Visit retention period¶
Controls how long visit records are kept in the database. Set a number of days (e.g. 90) to automatically purge older records on cron, or set to 0 (default) to keep all records indefinitely.
This is useful for high-traffic sites where the shorturl_visits
table can grow very large over time.
Slug modes¶
Each short URL uses one of three slug modes, selected when creating the node. Available modes are filtered by the current user's permissions.
Custom¶
The user enters a vanity slug manually (e.g. promo, sale2024).
Slugs are normalized to lowercase and validated for global
uniqueness. A slug may only contain letters, digits, hyphens and
underscores, and cannot be a path the site already answers (such as
user or admin, or a path alias), because its redirect would take
that page over. These rules apply to every save that validates the
node: the node form, REST and JSON:API, and the CSV import. A slug a
short URL already has is kept even if it breaks them, so older short
URLs stay editable and their QR codes keep working.
Permission: Use custom short URL slugs
Base36¶
A random slug is generated using cryptographically secure random
bytes encoded in base36 (characters 0-9, a-z). The length
is configurable in settings.
Slugs are case-insensitive
All slugs are normalized to lowercase on save. Unlike
case-sensitive shorteners (e.g. bit.ly where Abc and abc
are distinct), this module treats them as the same slug. This
matches the Redirect module's default behavior and avoids
user confusion with mixed-case URLs.
Permission: Use base36 short URL slugs
Auto-increment¶
Sequential numeric slugs (1, 2, 3, ...). The slug auto-increment counter, kept in Drupal's State API, holds the last number given out. If State loses it, for example after restoring a database without it, the next number follows the highest existing numeric slug.
Base36 and auto-increment slugs are drawn again when a redirect
already uses the generated slug (for example a custom slug 42), or
when the slug is a path of the site.
Permission: Use auto-increment short URL slugs
Multi-domain support
The Domain Short URL companion module adds per-domain slug scoping and per-domain slug auto-increment counters. The same slug can exist on multiple domains, each pointing to a different destination.
Permissions¶
The module provides nine granular permissions:
| Permission | Description |
|---|---|
| Use custom short URL slugs | Create short URLs with vanity slugs |
| Use base36 short URL slugs | Create short URLs with random slugs |
| Use auto-increment short URL slugs | Create short URLs with numeric slugs |
| Access short URL list | View the admin listing |
| Administer Short URL settings | Access the settings form (admin) |
| Access Short URL API | Use REST API endpoints |
| Import short URLs from CSV | Bulk-create short URLs from a CSV file |
| View short URL statistics | View stats on short URLs the user can view |
| View any short URL statistics | View stats on all nodes (admin) |
Redirect behavior¶
Redirects are managed automatically:
- On node create/update: redirects are recreated with the current slug, destination, language, and status code.
- On node delete: all associated redirects are removed.
- On unpublish: redirects are disabled (not deleted) so the slug remains reserved.
- On re-publish: redirects are re-enabled.
Multi-language¶
For each translation of a short URL node, a language-specific
redirect is created. Additionally, a language-neutral fallback
redirect (language code und) is created for each unique slug.
This ensures the redirect works even when the visitor's negotiated
language does not match any translation.
Path aliases¶
Take a short URL with the slug promo. If a page had the alias
/promo, /promo would show that page instead of redirecting:
the Redirect module resolves path aliases before it looks a request
up. So a short URL's slug is never given to an alias:
- The URL alias box of a content form, and the URL aliases
page, refuse
/promo. - Pathauto gives short URL nodes no alias: their address is their
slug. A short URL's title is its slug, so a pattern such as
/[node:title]would otherwise give the node the alias/promo. - Pathauto gives other content another ending,
/promo-0for example. - A slug cannot be a path that already has an alias, its own node's included.
An alias that is already stored is kept on later saves of its page. Running the database updates deletes the aliases that short URLs already have at their own slug. The update lists them, and the site log keeps a notice for each one. An alias that another page has at a slug stays, because it is that page's address: change the slug, or that page's alias, to make the short URL redirect again.
Admin views¶
The module ships two pre-configured Views:
- Short URLs at
/admin/content/short-urls— lists all short URL nodes with filters for slug, destination, mode, and publish status - Short URL visits at
/admin/reports/shorturl-visits— lists individual visit records with filters for node ID, referrer, and country code