Shlink

Shlink is a self-hosted URL shortening service written in PHP that gives you complete ownership of your short links and their analytics. Instead of sending traffic through a third-party platform like Bitly or TinyURL, you run Shlink on your own infrastructure under your own domain. Every click is logged with geolocation, device type, browser, referrer, and timestamp — all stored in a database you control.

The application exposes both a REST API and a command-line interface, so it fits naturally into automated workflows, CI/CD pipelines, and custom dashboards. An official web client (Shlink Web Client and Shlink Dashboard) can be pointed at any Shlink instance, and third-party integrations can consume the same documented API. API keys support per-domain and per-URL permissions, giving teams fine-grained access control.

Deployment is straightforward: grab the official Docker image or a pre-built dist package, wire it to MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, or SQLite, and run the installer. High-performance PHP application servers — RoadRunner and FrankenPHP — are both supported out of the box for production workloads that need worker-pool concurrency. Redis, RabbitMQ, and Mercure integrations allow real-time visit notifications and caching at scale.

As of v5.1, Shlink ships with a mature dynamic redirect rules engine that can branch on device type, browser, geolocation (country or city), language, IP address, query parameters, and ISO-8601 date conditions — enabling time-based campaigns, device-aware deep links, and geo-targeted marketing without any client-side JavaScript.

What You Get

• URL shortening - Creates short codes for any long URL with support for custom slugs, multi-segment paths, and configurable code lengths.
• Visit analytics - Captures geolocation, browser, device type, operating system, referrer, and timestamp for every click, with optional IP anonymization for GDPR compliance.
• Custom slugs - Lets you define human-readable short URLs such as yourdomain.com/summer-sale or yourdomain.com/docs/api-v2.
• Multi-domain support - Runs multiple short domains on a single Shlink instance, each with independent configuration and analytics isolation.
• Dynamic redirect rules - Routes visitors to different long URLs based on device type, browser, geolocation (country or city), language, IP address, query parameters, and ISO-8601 date conditions.
• Tags and campaign tracking - Organizes short URLs with custom tags and filters analytics by tag for campaign-level reporting.
• API-first architecture - Exposes a fully documented REST API with versioned endpoints, API key authentication, and role-based access control per domain or URL.
• Real-time visit events - Publishes click events to Mercure, RabbitMQ, and Redis Pub/Sub channels so dashboards and automation tools receive updates instantly.
• Bot detection - Filters crawlers and bots from visit statistics using a maintained detection library so reported counts reflect real human traffic.
• Third-party URL imports - Migrates existing short links from Bitly, YOURLS, Kutt, and other providers via CSV or API without breaking existing links.
• GDPR-ready IP handling - Anonymizes visitor IP addresses by default, retaining geolocation data while discarding the precise address.
• Multi-database engine support - Works with MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, and SQLite through Doctrine ORM with full migration tooling.

Common Use Cases

• Marketing campaign tracking - A growth team creates branded short links per channel, uses tags to segment traffic, and monitors click-through rates across email, social media, and paid ads through the REST API.
• Enterprise link management - A corporate IT department self-hosts Shlink to eliminate vendor dependency, enforce IP anonymization for compliance, and manage thousands of internal redirect links through the CLI.
• Developer API integration - A SaaS product integrates Shlink’s REST API to offer branded URL shortening as a feature, issuing per-customer API keys with domain-restricted permissions.
• Device-aware deep linking - A mobile app publisher uses dynamic redirect rules to send iOS users to the App Store, Android users to Google Play, and desktop users to the web app — all from one short link.
• Time-limited promotional links - A retailer configures date-based redirect conditions so a campaign URL automatically switches destination after the sale ends, without updating the short link itself.
• Real-time analytics pipelines - A data team subscribes to Mercure or RabbitMQ visit events to stream click data into their data warehouse, eliminating polling and reducing database query load.

Under The Hood

Architecture Shlink is organized as a three-module application — Core, Rest, and CLI — sharing a common domain layer that handles all business logic while each interface module provides its own entry point, routing, and input parsing. The Core module is further subdivided into bounded contexts (ShortUrl, Visit, RedirectRule, Domain, Geolocation, EventDispatcher) that communicate through interfaces rather than concrete classes, enforcing clear contracts between layers. Dependency injection is managed by Laminas ServiceManager with ConfigProvider classes that aggregate service definitions from per-module configuration files, making it straightforward to swap infrastructure implementations without touching domain logic. Redirect resolution follows a clean chain: the request hits a PSR-15 middleware stack, the ShortUrlResolver looks up the entity, the ShortUrlRedirectionResolver evaluates the ordered list of redirect rules against the incoming request, and a redirect response is emitted — all without client-side JavaScript.

Tech Stack Shlink runs on PHP 8.4 or 8.5 using the Mezzio microframework for PSR-15 middleware routing, Laminas components for dependency injection and input filtering, and Doctrine ORM 3.x with DBAL 4.x for database abstraction across MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, and SQLite. Short code generation uses the nanoid-php library with a collision-resistant uniqueness check backed by a database lock. High-throughput deployments use either Spiral’s RoadRunner (a Go-based worker pool) or FrankenPHP (a Caddy-embedded PHP server) in place of the traditional FPM setup. Background work flows through a job queue backed by RabbitMQ or Redis, and real-time push notifications go out over Mercure. Static analysis runs PHPStan at level max with Doctrine, PHPUnit, and Symfony extensions enabled.

Code Quality The codebase demonstrates strong type discipline throughout — readonly constructors, property hooks (a PHP 8.4 feature used on ShortUrl’s longUrl setter), union types, enums for condition types and visit types, and explicit interface contracts on every public service. The test suite is layered into unit tests, database integration tests, API integration tests, and CLI integration tests, each with its own PHPUnit configuration and parallelized CI execution via veewee/composer-run-parallel. Code style is enforced by Mago (a Rust-based PHP formatter and linter) combined with PHPStan at the strictest level, with CI blocking merges on any violation. Exception handling is explicit and domain-specific, with typed exception classes that map cleanly to HTTP problem detail responses in the REST layer.

What Makes It Unique Shlink’s dynamic redirect rules engine stands out as genuinely sophisticated for a URL shortener: eleven condition types — device, browser, language, IP address, country, city, before-date, after-date, query-param (with value, any-value, and valueless variants) — can be combined in ordered rule sets per short URL, evaluated entirely server-side at redirect time without any client-side scripting. This makes Shlink the only self-hosted shortener that can handle geo-targeted, device-aware, time-bounded, and parameter-conditional redirects from a single link. The adoption of PHP 8.4 property hooks and readonly semantics in the core entity shows a commitment to using the language’s latest capabilities to enforce invariants at the type level rather than runtime checks.

Self-Hosting

Shlink is released under the MIT License, which grants unrestricted rights to use, copy, modify, distribute, and sublicense the software for any purpose including commercial use. There are no copyleft obligations — you do not need to open-source applications you build on top of Shlink, and there is no contributor license agreement or dual-licensing model. The only requirement is to keep the copyright notice in redistributed copies. This makes it straightforwardly usable in commercial environments without legal friction.

Operating Shlink yourself means taking on full responsibility for infrastructure provisioning, uptime, database backups, SSL termination, and software updates. A typical production setup requires a PHP 8.4+ environment (or the official Docker image), a supported SQL database, and optionally Redis for caching, RabbitMQ or Mercure for real-time events, and a reverse proxy for HTTPS. The Shlink installer CLI guides initial configuration, and Doctrine migrations handle schema upgrades between versions. Release cadence is high — v5.1 shipped five patch releases in one week in June 2026 — so staying current requires a reliable update workflow. The MaxMind GeoLite2 database for geolocation requires a free MaxMind account and periodic downloads; Shlink provides an automated update command but the operator must schedule and monitor it.

Shlink has no official managed cloud offering or paid enterprise tier — the hosted alternative is using a commercial URL shortener SaaS such as Bitly or Rebrandly. Compared to those services, self-hosting means you accept zero vendor uptime guarantees, no enterprise support contracts, and no managed database backups. What you gain is complete data ownership, the ability to use your own domain, no per-click pricing, and full customization of the redirect rules engine and analytics pipeline. The active community on GitHub and comprehensive documentation at shlink.io are the primary support channels.