[opensourcedex]

Shlink is a free, open source marketing & customer engagement project written in PHP and released under MIT. It has 5,293 GitHub stars, 413 forks and 22 open issues, and was last pushed 7 days ago. On this registry it ranks #20 of 50 tracked projects in Marketing & Customer Engagement, with 5 head-to-head comparisons available. It gained 13 stars over the last 6 tracked days.

What is Shlink?

What it is

Shlink is a self-hosted URL shortener written in PHP, published under the MIT license, and maintained in the Shlink ecosystem that includes the shlink.io site and accompanying documentation. It runs as a service that serves shortened links under a domain chosen by the operator, rather than under a domain controlled by a third party. The project is built with the Laminas and Mezzio frameworks and exposes its functionality through a REST API, which is how clients and integrations drive it programmatically.

The concrete problem it solves is ownership of short links. Teams that need branded, stable short URLs, and that still want to query and manage them later, would otherwise depend on an external shortening service whose domain, retention policy, and business model sit outside their control. Shlink moves that responsibility in-house: the operator supplies PHP, a database, and a web server, and Shlink issues and resolves the short codes. Because everything is exposed over a REST API, the same backend can serve a web interface, a CLI, or a custom application, and the link data stays in a database the operator can read, back up, and migrate.

Key capabilities

  • Shortens URLs and redirects requests to the destination under a domain the operator controls.
  • Exposes a REST API for creating, listing, and managing short URLs and their visits.
  • Provides a command-line interface, including shlink -V for reporting the installed version.
  • Runs against MySQL, MariaDB, PostgreSQL, Microsoft SQL, or SQLite, through the matching pdo_mysql, pdo_pgsql, pdo_sqlsrv, or pdo_sqlite driver.
  • Integrates with a RabbitMQ instance, which requires the sockets and bcmath PHP extensions.
  • Supports RoadRunner as a runtime, in which case APCu is not required.
  • Accepts configuration through environment variables when run from the official Docker image.

Who uses it and how

  • Teams that need branded short links under their own domain deploy Shlink behind internal infrastructure and hand out links on that domain.
  • Operators who prefer containers generate a container from the official Docker image and supply custom configuration through environment variables.
  • Applications that manage links programmatically call the REST API to create and track short URLs rather than hand-editing records.
  • Administrators who want a packaged deployment download the pre-bundled shlink*_dist.zip release that matches their PHP version and decompress it in the target location.
  • Contributors and operators who need a specific build clone the repository, fetch Composer, and run ./build.sh 3.0.0 to produce a dist file inside the build directory.

Getting started

The documented paths are the official Docker image with configuration passed as environment variables, or a self-hosted install from a pre-bundled shlink*_dist.zip release, or a build from source using git and Composer followed by ./build.sh. Self-hosting requires PHP 8.4 or 8.5 with the json, curl, pdo, intl, gd, and gmp or bcmath extensions, plus one of the supported databases and its matching PDO driver.

When to use it — and when not to

Shlink suits operators who want short links to live on their own domain and who are willing to

project readme (upstream, from github) — read inline

Shlink

Build Status Code Coverage Latest Stable Version Docker pulls License

Mastodon Bluesky Paypal donate

A PHP-based self-hosted URL shortener that can be used to serve shortened URLs under your own domain.

Table of Contents

Full documentation

This document contains the very basics to get started with Shlink. If you want to learn everything you can do with it, visit the full searchable documentation.

Docker image

You can learn how to use the official docker image by reading the docs.

The idea is that you can just generate a container using the image and provide the custom config via env vars.

Self-hosted

First, make sure the host where you are going to run shlink fulfills these requirements:

  • PHP 8.4 or 8.5
  • The next PHP extensions: json, curl, pdo, intl, gd and gmp/bcmath.
    • apcu extension is recommended if you don't plan to use RoadRunner.
    • sockets and bcmath extensions are required if you want to integrate with a RabbitMQ instance.
  • MySQL, MariaDB, PostgreSQL, MicrosoftSQL or SQLite.
    • You will also need the corresponding pdo variation for the database you are planning to use: pdo_mysql, pdo_pgsql, pdo_sqlsrv or pdo_sqlite.

Download

In order to run Shlink, you will need a built version of the project. There are two ways to get it.

  • Using a dist file

    The easiest way to install shlink is by using one of the pre-bundled distributable packages.

    Go to the latest version and download the shlink*_dist.zip file that suits your needs. You will find one for every supported PHP version.

    Finally, decompress the file in the location of your choice.

  • Building from sources

    If for any reason you want to build the project yourself, follow these steps:

    • Clone the project with git (git clone https://github.com/shlinkio/shlink.git), or download it by clicking the Clone or download green button.
    • Download the Composer PHP package manager inside the project folder.
    • Run ./build.sh 3.0.0, replacing the version with the version number you are going to build (the version number is used as part of the generated dist file name, and to set the value returned when running shlink -V from the command line).

    After that, you will have a dist file inside the build directory, that you need to decompress in the location of your choice.

    Note

    This is the process used when releasing new Shlink versions. After tagging the new version with git, the GitHub release is automatically created by a GitHub workflow, attaching the generated dist file to it.

Configure

Despite how you built the project, you now need to configure it, by following these steps:

  • If you are going to use MySQL, MariaDB, PostgreSQL or Microsoft SQL Server, create an empty database with the name of your choice.
  • Recursively grant write permissions to the data directory. Shlink uses it to cache some information.
  • Set up the application by running the vendor/bin/shlink-installer install script. It is a command line tool that will guide you through the installation process. Take into account that this tool has to be run directly on the server where you plan to host Shlink. Do not run it before uploading/moving it there.
  • Generate your first API key by running bin/cli api-key:generate. You will need the key in order to interact with Shlink's API.

Using shlink

Once shlink is installed, there are two main ways to interact with it:

  • The command line: Try running bin/cli to see all the available commands.

    All of them can be run with the --help/-h flag in order to see how to use them and all the available options.

    It is probably a good idea to symlink the CLI entry point (bin/cli) to somewhere in your path, so that you can run shlink from any directory.

  • The REST API: The complete docs on how to use the API can be found here, and a sandbox which also documents every endpoint can be found in the API Spec portal.

    However, you probably don't want to consume the raw API yourself. That's why a nice web client is provided that can be directly used from https://app.shlink.io, or hosted by yourself.

Both the API and CLI allow you to do mostly the same operations, except for API key management, which can be done from the command line interface only.

Contributing

If you are trying to find out how to run the project in development mode or how to provide contributions, read the CONTRIBUTING doc.

Powered by

Thanks to JetBrains for their continuous support to this project in the form of IDE licenses.

JetBrains logo

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com

Frequently asked questions

Is Shlink free to use?

Shlink is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does Shlink do?

The definitive self-hosted URL shortener

What is Shlink written in?

Shlink is primarily written in PHP. Its source is publicly available at https://github.com/shlinkio/shlink, and it has 5,293 GitHub stars.