badmushroom/shorties

A simple URL shortner for Laravel applications.

dev-main 2026-06-04 13:11 UTC

Requires

• php: >=8.0

MIT

• Chris Sprague

• links
• URL-Shortener

README

Shorties

A Laravel package for generating, managing, and tracking short URLs — complete with analytics, customizable routing, view overrides, and pruning.

Features

• Generate short URLs with custom or random codes
• Subdomain or path-based routing (configurable)
• Visitor analytics tracking (with fingerprinting, user agent, etc.)
• Optional view override for 404-style "link not found" page
• Artisan commands for creating and listing short links
• Configurable data retention with built-in Laravel pruning support

Installation

composer require badmushroom/shorties

Publish config and views (optional):

php artisan vendor:publish --tag=shorties-config
php artisan vendor:publish --tag=shorties-views

Run migrations:

php artisan migrate

Configuration

In config/shorties.php:

Key	Description
route_mode	subdomain or path
subdomain	Subdomain to use for short links (e.g. go)
prefix	URI prefix to use if using path mode (e.g. shorties)
middleware	Middleware group applied to short URL routes (web, api, etc.)
track_analytics	Enable or disable tracking of short URL visits
analytics_retention_days	Number of days to keep analytics records before pruning

Example .env settings

SHORTIES_ROUTE_MODE=path
SHORTIES_PATH=shorties
SHORTIES_TRACK_ANALYTICS=true
SHORTIES_ANALYTICS_RETENTION_DAYS=90

Routing

Shorties can handle links either by subdomain or by path:

Subdomain-based

https://go.example.com/my-short-code

'route_mode' => 'subdomain',
'subdomain' => 'go',

Path-based

https://example.com/shorties/my-short-code

'route_mode' => 'path',
'prefix' => 'shorties',

Analytics Tracking

When track_analytics is enabled, Shorties dispatches a job on each visit that records:

• UUID of the URL
• Timestamp (visited_at)
• User agent
• Fingerprint (if provided)

Records are stored in shorties_analytics.

Pruning Old Analytics

Shorties supports Laravel's Model Pruning to automatically remove old analytics data.

Add this to your scheduler:

$schedule->command('model:prune')->daily();

Configure retention via:

SHORTIES_ANALYTICS_RETENTION_DAYS=90

Or update config/shorties.php.

You can prune manually with:

php artisan model:prune --model="BadMushroom\Shorties\Models\Analytic"

Artisan Commands

Create a new short link

php artisan shorties:links:create

Interactively prompts for a long URL and optional short code.

List short links

php artisan shorties:links

Displays a table of existing short codes, their URLs, visit counts, and creation timestamps.

Customizing the 404 View

To show a custom "link not found" page, publish the default view:

php artisan vendor:publish --tag=shorties-views

Then edit:

resources/views/vendor/shorties/not-found.blade.php

Security & Notes

• Uses UUIDs for both URL and analytic IDs
• Tracks analytics only if enabled via config
• Prunes old records based on configurable retention
• Routes are scoped to either a path or subdomain

Testing

vendor/bin/phpunit

License

This package is open-sourced software licensed under the MIT license.

Made by Bad Mushroom