YOURLS — Your Own URL Shortener

Introduction

YOURLS (Your Own URL Shortener) is a lightweight PHP application that lets you run a private or public URL shortening service on your own domain. It gives you ownership of your link data, detailed analytics on every shortened URL, and a plugin system for extending functionality.

What YOURLS Does

• Shortens long URLs with custom or auto-generated keyword slugs on your own domain
• Tracks click statistics including referrers, geographic location, and timestamps
• Provides a bookmarklet for one-click URL shortening from any browser
• Exposes a JSON/XML API for programmatic URL creation and stat retrieval
• Supports private (admin-only) or public (anyone can shorten) operation modes

Architecture Overview

YOURLS is a PHP application that stores URLs, click data, and configuration in a MySQL database. It runs behind any standard web server (Apache, Nginx) with PHP support. URL redirection is handled via server rewrite rules that route short URLs through a PHP dispatcher. The admin interface is a server-rendered PHP dashboard. The codebase is intentionally minimal with no heavy framework dependencies.

Self-Hosting & Configuration

• Requires PHP 7.4+ and MySQL 5.0+ with a standard web server
• Copy user/config-sample.php to user/config.php and set database credentials
• Define your short domain, admin username/password, and URL scheme in config
• Optional: configure YOURLS behind a reverse proxy with proper YOURLS_SITE setting
• Docker images are available from the community for containerized deployment

Key Features

• Custom short URLs with user-defined keywords (e.g., yourdomain/my-link)
• Detailed per-link analytics with historical click graphs and referrer tracking
• Plugin architecture with 100+ community plugins for spam filtering, QR codes, and more
• Passwordless API with signature-based token authentication
• JSON, XML, and plaintext output formats for API responses

Comparison with Similar Tools

• Shlink — Modern PHP alternative with Docker-first design and multi-domain support
• Kutt — Node.js-based, includes link expiration and password protection
• Polr — Laravel-based, modern UI but less actively maintained
• Bit.ly — SaaS with polished analytics, but your data lives on their servers
• Short.io — Managed service with custom domains, no self-hosting option

FAQ

Q: Can I use a custom domain with YOURLS? A: Yes. YOURLS is designed to run on your own domain. You set the domain in the configuration file and point your DNS and web server to it.

Q: Is YOURLS suitable for high-traffic use? A: YOURLS handles moderate traffic well. For high-volume deployments, enable the built-in page cache plugin and use a reverse proxy cache in front of the application.

Q: How do I migrate from another URL shortener? A: YOURLS provides an import API and community plugins for migrating from services like Bit.ly. You can also bulk-import URLs via the API or direct database insertion.

Q: Does YOURLS support link expiration? A: Not by default, but community plugins add time-based link expiration, click limits, and conditional redirects.

Sources

• https://github.com/YOURLS/YOURLS
• https://yourls.org