Shlink is a PHP-based, self-hosted URL shortener designed for users who want full control over their shortened links without relying on third-party services. It enables organizations and individuals to create custom-branded short URLs using their own domain, with full data ownership and privacy. Built on Mezzio and Laminas, Shlink provides both a REST API and command-line interface for managing links, making it ideal for developers, DevOps teams, and sysadmins who need to integrate URL shortening into their workflows or internal tools. Unlike cloud-based alternatives, Shlink runs entirely on your infrastructure, ensuring compliance with data policies and eliminating tracking or ads.
What You Get
- Self-hosted URL shortening - Host your own branded short URLs on your domain with full control over data, no third-party dependencies.
- REST API with comprehensive endpoints - Programmatically create, list, update, and delete short links using a documented REST API with Swagger-based documentation at api-spec.shlink.io.
- Command-line interface (CLI) - Manage links and API keys directly via terminal commands like
bin/cli short-url:generate or bin/cli api-key:generate.
- Database support for multiple backends - Supports MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, and SQLite with corresponding PDO extensions.
- Docker container ready - Official Docker image available via shlinkio/shlink on Docker Hub, configurable via environment variables for quick deployment.
- Web client (shlink-web-client) - A responsive, self-hostable web interface for managing links visually, available at app.shlink.io or deployable locally.
- APCu and Redis-compatible caching - Optional APCu extension for performance optimization; supports RabbitMQ via sockets and bcmath extensions for async processing.
Common Use Cases
- Building a marketing campaign with branded short links - A digital marketer uses Shlink to generate trackable, domain-branded URLs (e.g., yourbrand.link/deal) for email and social media campaigns, with full analytics and link expiration control.
- Creating an internal tool for IT teams - A DevOps team deploys Shlink on their private network to generate short links for internal documentation, ticketing systems, and incident response URLs to avoid exposing long, messy URLs.
- Problem: Third-party URL shorteners block or limit usage → Solution: Self-hosted Shlink - A company hit rate limits on bit.ly or TinyURL; they migrate to Shlink to eliminate restrictions, ensure link permanence, and add custom branding.
- Team workflow for developers managing API endpoints - A development team uses the Shlink CLI to generate short URLs for staging environments and share them via Slack bots or CI/CD pipelines using the API key generated with
bin/cli api-key:generate.
Under The Hood
Shlink is a robust, PHP-based URL shortening service designed with modularity, extensibility, and developer-friendly operations in mind. It supports a range of deployment models and integrates modern tools to provide both API-driven and CLI-based administration capabilities.
Architecture
Shlink follows a layered and modular architecture that emphasizes separation of concerns and flexibility in deployment.
- The application is structured around distinct functional modules such as API key management, geolocation, caching, and real-time updates, enabling clear division of responsibilities.
- It leverages dependency injection and configuration-driven design to support diverse runtime environments and seamless integration with external systems.
- Design patterns such as factory and delegator factories are used to manage service instantiation and middleware integration effectively.
- Component interactions are orchestrated through a service container, with extensive use of event-driven mechanisms for tracking and updating data in real time.
Tech Stack
Built with modern PHP frameworks and tools, Shlink utilizes a variety of technologies to ensure scalability and maintainability.
- The core is developed in PHP, using Laminas and Mezzio for HTTP handling and dependency injection, forming a solid foundation for web services.
- Key dependencies include Doctrine ORM for database operations, Redis for caching and locking, and RoadRunner for high-performance HTTP handling.
- Development and deployment are supported through Docker, Composer, and environment-specific configuration files for flexible setups.
- Testing is carried out using PHPUnit with comprehensive test suites covering API, CLI, and database layers.
Code Quality
Shlink demonstrates a mature approach to code quality with consistent practices and extensive test coverage.
- The codebase is well-tested using PHPUnit, with a broad range of tests ensuring functionality across different modules and environments.
- Error handling is implemented consistently with try/catch blocks and appropriate exception types, enhancing reliability in runtime scenarios.
- PHP conventions are followed with clear naming and modular structure, though some technical debt exists in the configuration-heavy approach.
What Makes It Unique
Shlink distinguishes itself through its modular architecture, real-time capabilities, and support for modern deployment practices.
- Its modular design enables flexible deployment models—supporting both CLI and API-based administration with seamless integration between the two.
- Integration with Mercure allows for real-time updates to short URL statistics without polling, offering a modern alternative to traditional methods.
- Configuration is handled in a layered fashion using environment variables and config files, supporting easy customization across environments.
- A comprehensive test suite ensures consistent behavior in various setups, including isolated Docker-based testing for development and CI pipelines.