A self-hosted and PHP-based URL shortener application with CLI and REST interfaces
Clone or download
acelaya Merge pull request #217 from acelaya/feature/deprecated-endpoints
Noticed that old endpoints will keep working
Latest commit 2241279 Sep 24, 2018
Permalink
Failed to load latest commit information.
bin Ensured install tool knows the install command is the only one Sep 16, 2018
config Created and registered middleware which replaces short-code from shor… Sep 20, 2018
data Created migration fixing cascade delete on visits table Sep 15, 2018
docs/swagger Fixed references to short codes where actually short URLs are being m… Sep 24, 2018
module More classes renamed and fixes for usage of the short code concept in… Sep 20, 2018
public Adds robots.txt and disallows all Sep 9, 2018
.env.dist Removed rest auth env vars Aug 7, 2016
.gitattributes Added phpstan config file to export-ignore list Dec 30, 2017
.gitignore Ordered gitignore placing all composer-related files together Sep 11, 2018
.phpstorm.meta.php Moved command and app creation logic to a factory for install scripts Jul 5, 2017
.scrutinizer.yml Added CI config files Apr 17, 2016
.travis.yml Added automatic release generation to travis config Sep 24, 2018
CHANGELOG.md Updated changelog with v1.12 Sep 15, 2018
LICENSE Updated date in license Sep 9, 2018
README.md Added note in readme file that travis is the one creating Github rele… Sep 24, 2018
build.sh Improved build process to not require parent dir, sudo and exclude dirs Sep 24, 2018
composer.json Created migration which parses existing IP addresses, generating hash… Sep 13, 2018
docker-compose.override.yml.dist Udated minimum PHP version and docker stuff Oct 12, 2017
docker-compose.yml Updated PathVersionMiddleware so that it is only applied to rest routes Jan 21, 2017
func_tests_bootstrap.php Ensured same testing database is used to generate with entities and t… Oct 23, 2017
indocker Created docker-related files Jan 19, 2017
infection.json Updated to phpstan 0.10 and infection 0.9 Jul 4, 2018
migrations.yml Added doctrine migrations and remove platform specific code from enti… Aug 19, 2016
phpcs.xml Improved coding styles Oct 12, 2017
phpstan.neon Fixed coding styles Jul 31, 2018
phpunit-func.xml Implemented EditShortCodeAction Jan 7, 2018
phpunit.xml.dist Implemented EditShortCodeAction Jan 7, 2018

README.md

Shlink

Build Status Code Coverage Scrutinizer Code Quality Latest Stable Version License Paypal donate

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

Installation

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

  • PHP 7.1 or greater with JSON, APCu, intl, curl, PDO and gd extensions enabled.
  • MySQL, PostgreSQL or SQLite.
  • The web server of your choice with PHP integration (Apache or Nginx recommended).

Then, you will need a built version of the project. There are a few ways to get it.

  • Using a dist file

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

    Just go to the latest version and download the shlink_X.X.X_dist.zip file you will find there.

    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 1.0.0, replacing the version with the version number you are going to build (the version number is only used for the generated dist file).

    After that, you will have a shlink_x.x.x_dist.zip dist file inside the build directory.

    This is the process used when releasing new shlink versions. After tagging the new version with git, the Github release is automatically created by travis, attaching generated dist file to it.

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

  • If you are going to use MySQL or PostgreSQL, 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.

  • Setup the application by running the bin/install script. It will guide you through the installation process.

  • Configure the web server of your choice to serve shlink using your short domain.

    For example, assuming your domain is doma.in and shlink is in the /path/to/shlink folder, this would be the basic configuration for Nginx and Apache.

    Nginx:

    server {
        server_name doma.in;
        listen 80;
        root /path/to/shlink/public;
        index index.php;
        charset utf-8;
    
        location / {
            try_files $uri $uri/ /index.php$is_args$args;
        }
    
        location ~ \.php$ {
            fastcgi_split_path_info ^(.+\.php)(/.+)$;
            fastcgi_pass unix:/var/run/php/php7.1-fpm.sock;
            fastcgi_index index.php;
            include fastcgi.conf;
        }
    
        location ~ /\.ht {
            deny all;
        }
    }

    Apache:

    <VirtualHost *:80>
        ServerName doma.in
        DocumentRoot "/path/to/shlink/public"
    
        <Directory "/path/to/shlink/public">
            Options FollowSymLinks Includes ExecCGI
            AllowOverride all
            Order allow,deny
            Allow from all
        </Directory>
    </VirtualHost>
  • 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.

  • Finally access to https://app.shlink.io and configure your server to start creating short URLs.

Bonus

There are a couple of time-consuming tasks that shlink expects you to do manually, or at least it is recommended, since it will improve runtime performance.

Those tasks can be performed using shlink's CLI, so it should be easy to schedule them to be run in the background (for example, using cron jobs):

  • Resolve IP address locations: /path/to/shlink/bin/cli visit:process

    If you don't run this command regularly, the stats will say all visits come from unknown locations.

  • Generate website previews: /path/to/shlink/bin/cli shortcode:process-previews

    Running this will improve the performance of the doma.in/abc123/preview URLs, which return a preview of the site.

Update to new version

When a new Shlink version is available, you don't need to repeat the whole process yourself.

Instead, get the latest version as explained in previous step, and then, run the script bin/update.

The script will ask you for the location from previous shlink version, and use it in order to import the configuration.

It will then update the database and generate some assets.

Right now, it does not import cached info (like website previews), but it will. By now you will need to regenerate them again.

Important! It is recommended that you don't skip any version when using this process. The update gets better on every version, but older versions might make assumptions.

Using a docker image

Currently there's no official docker image, but there's a work in progress alpha version you can find here.

The idea will be that you can just generate a container using the image and provide predefined config files via volumes or CLI arguments, so that you get shlink up and running.

Currently the image does not expose an entry point which let's you interact with shlink's CLI interface, nor allows configuration to be passed.

Using shlink

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

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

    All of those commands 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 here.

    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 you can host it yourself too.

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