UrlHub, a self-hosted Laravel shortener, and the configuration file that decides how open it is

A self-hosted shortener that expects you to read the configuration file

UrlHub is a URL shortener built as a Laravel application, and the description of the project is that you host your own shortener and get a set of useful features in return. It is created and maintained by Budi Hermawan, and the repository is MIT licensed with a Laravel 13 badge.

What distinguishes it from a minimal shortener is the feature list, and it is worth reading the list for what it implies about the code. Custom URLs let a user write example.com/laravel instead of a random string. QR code generation is there because transferring a link to a phone is easier by scanning than by typing. Links can be edited, in both the short path and the destination, and can be deleted outright, which the documentation points out is not available with most shorteners. Device aware redirection sends mobile visitors to a different URL depending on the operating system. A password can protect the destination. A link can be given an expiration date and time, with a separate expiration URL to redirect to afterwards, and query parameters from the short link are forwarded to the destination. There is a page that shows where a link goes before you click it, a dark mode, and a sortable list of shortened URLs.

The customisation story is the part that determines whether this is for you. The documentation states that you can decide whether anyone can register, whether users must be registered to create a short URL, and from the configuration file you can edit pretty much everything about the site. That is the design: a single-tenant instance you run for your team, your company or your community, rather than a public multi-tenant service.

The project is not archived and the last push was on 2026-07-12, with v1.20.0 released on 2026-05-29 and v1.19.0 on 2025-09-29.

Requirements and the five commands that get it running

UrlHub is a Laravel application, which means it needs a Laravel application setup: PHP 8.4 or newer, a web server such as Apache or Nginx, and a database, with MySQL, MariaDB or SQLite named as options.

The installation sequence in the documentation is short. Rename the .env.example file to .env, or copy it, and update it to your needs. Then run composer install, then php artisan key:generate, then php artisan migrate --seed, and then php artisan serve to bring it up. The seed step is what creates the first accounts, and the documentation lists them in a table: [email protected] with the username admin and the password admin for Admin Access, and [email protected] with the username user and the password user for User Access. Those credentials are obviously for a local first run and not for anything exposed to a network, which is worth saying plainly because a seeded admin account with a known password is exactly the kind of thing that gets deployed by accident.

The .env file itself is the main surface for configuration, and reading the example tells you what the application assumes. The application block sets APP_NAME, an empty APP_KEY that key:generate fills in, APP_TIMEZONE of UTC, APP_URL, English locale settings, APP_ENV of local and APP_DEBUG set to true, with a debug bar toggle and a maintenance driver of file. The database block points at mysql on 127.0.0.1 with the database named urlhub.

bash DB_CONNECTION=mysql DB_COLLATION=utf8mb4_unicode_ci DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=urlhub DB_USERNAME=root DB_PASSWORD=

The session block is where a self-hosted deployment usually needs attention, since the example uses the database driver:

bash SESSION_DRIVER=database SESSION_LIFETIME=120 SESSION_ENCRYPT=false SESSION_PATH=/ SESSION_DOMAIN=null

Beyond that the example shows the breadth of Laravel integrations the app ships with, from cache and queue drivers through Redis, Memcached, mail and S3 style AWS keys. Most of those are defaults you would change, but their presence tells you the application is configured through the standard Laravel config layer rather than something custom.

Front-end assets are Vite and Tailwind, and they need a separate build

The interface is a modern one, and the asset pipeline is not part of the composer install. After the PHP side is up, the documentation has a separate step for bundling the application's assets, which begins with npm install and then offers two scripts:

bash # Run the Vite development server... npm run dev

# Build and version the assets for production... npm run build

The package manifest is marked private and typed as a module, and the scripts are dev running vite and build running vite build. The dependencies tell you what the front end is made of: Tailwind CSS at version 4.3.0 with the separate forms plugin, the Tailwind Vite plugin, the Vite plugin for Laravel, Vite itself at 7.3.3, plus clipboard for copy to clipboard behaviour and flatpickr for date and time picking. The flatpickr dependency is a direct hint about the link expiration feature, since choosing an expiry date and time needs a picker.

The practical consequence is that a deployment has two build steps, one for PHP and one for JavaScript, and the second one is easy to forget because the Laravel side of the install is otherwise complete. The repository layout shows the standard Laravel skeleton, with app/, bootstrap/, config/, database/, public/, resources/, routes/, storage/ and tests/ directories, alongside artisan and composer.json. The front end configuration is vite.config.js and tailwind.config.js, and there is a .vscode/ directory for editor setup.

There is also a static analysis setup, with phpstan.neon.dist and a phpstan-baseline.neon in the root, plus a .php-cs-fixer.dist.php for code style. A committed baseline for PHPStan is a common Laravel practice and it tells you the project acknowledges a set of pre-existing findings rather than claiming a clean analysis.

Running the test suite and the project's own quality gates

The documentation gives three equivalent ways to run the tests from the project root: php artisan test, or composer test, or ./vendor/bin/phpunit. The three are the same suite reached through the Laravel test command, the Composer script, and PHPUnit directly. The repository has phpunit.xml.dist at the root and a tests/ directory.

What is notable is the shape of the project rather than any single feature. It has a static analysis configuration with a baseline, a code style fixer configuration, a modern asset pipeline with Tailwind 4 and Vite 7, a conventional Laravel directory layout, and a test suite with three documented entry points. That is the profile of a maintained application rather than a script.

The contribution notes are also unusually thorough for a project of this size, and they are worth reading as a signal about how the project is run. The documentation asks contributors to issue pull requests to cover niche use cases, to ask their employer to use UrlHub in projects, and to contribute to the core repository. The bug report section asks for a title, a clear description and a code sample that demonstrates the issue, and it says plainly not to expect that a bug report will automatically see any activity. That last line is an accurate description of a volunteer project and a more honest one than most.

For a security issue, the documentation routes reporting differently. It asks you to search the existing GitHub issues first, then open a new issue if nothing matches, and it separates problems that are not a security risk from those that are.

Where UrlHub is the wrong tool

The first wrong case is a public multi-tenant shortener with anonymous signup. The configuration can require registration and can control who registers, but the default example configuration does not close registration by itself, and the seeded admin and user accounts exist from the first migration. Turning a self-hosted instance into an open service is a policy and abuse problem that no feature list solves.

The second wrong case is a deployment where you do not want a database-backed session and a debug flag left on. The example .env sets APP_DEBUG to true and uses the database session driver, and shipping that unchanged on an internet facing host is a bad first week. The fix is ordinary Laravel practice, but it means the first thing you do is edit a configuration file rather than run the app.

The third wrong case is a project that needs analytics, an API or a link management workflow at scale. The feature list is about the link itself, custom slugs, protection and expiry, and the documentation does not describe an API for creating links programmatically, per-link click statistics, or a bulk import path. A marketing team that wants a dashboard of click counts over campaigns is looking at a different class of tool.

The fourth wrong case is a team that does not want to run a web server and a database. UrlHub is a self-hosted Laravel application with a PHP 8.4 requirement and a database. It is not a static site generator with a shortener backend, and it is not a serverless function.

The fifth wrong case is expecting a maintained upstream for a feature you need. The last push was on 2026-07-12 and the most recent release, v1.20.0, dates from 2026-05-29, with the one before it from 2025-09-29. The project is alive, but release intervals are not tight, so plan around a feature request landing on someone else's schedule.

UrlHub against building a shortener on a hosted platform

The alternative is not another self-hosted shortener but a hosted one, and the difference in approach is about who absorbs the operational work.

A hosted service absorbs the servers, the databases, the TLS certificates, the abuse response and the uptime. You get a short link in seconds and an interface that already works on every phone browser. What you give up is the data and the configuration. There is no configuration file to set, because there is nothing to configure. You cannot decide who may register, because registration is the service's business model. You cannot edit the destination of a link that has already been shared, because the service holds the mapping and the contract with its users is different. And the domain is the provider's, not yours, so the links carry their brand.

UrlHub makes the opposite set of choices. You own the domain, so the short links are on your own hostname. You own the configuration, so registration policy, custom slugs, expiry and password protection are yours to set. You own the database, so the link list is yours to query. The cost is everything that follows: a web server, a database, a PHP runtime, a session store, an asset build, a key, a mail configuration if you want password protected links to send anything, and the discipline to change the seeded credentials and the debug flag before the first request arrives.

There is a third shape, the tiny one. A shortener can be a single function plus a table, deployed on a platform as a service or a container, with no admin interface at all. That is smaller and cheaper to run than UrlHub, but it gives up the features that make UrlHub a shortener rather than a redirect table: the editing, the deletion, the expiry, the password, the QR code and the dark mode are the application.

So the choice is between owning the whole thing and owning none of it. UrlHub sits in the middle, with a full admin interface and a real feature set, and a deployment checklist that you have to work through yourself.

Editorial conclusion

UrlHub suits an organisation that wants a shortener on its own domain with its own rules about who may create links, and that is prepared to run a PHP application with a database rather than a hosted service. It does not suit a team wanting a public multi-tenant shortener with anonymous signup, click analytics or a programmatic API, since none of those are described in the documentation. Before you put it on a server, edit .env so APP_DEBUG is false and the seeded admin and user accounts no longer carry the passwords admin and user, decide whether sessions stay in the database, run the separate npm run build step for the front end, and check the release history yourself, since v1.20.0 from 2026-05-29 is the most recent tag while the last push was on 2026-07-12.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. realodix/urlhub on GitHub
5. Releases