Download the PHP package yorcreative/laravel-urlshortener without Composer

Laravel URL Shortener

A Laravel URL Shortener package that provides URL redirects with optionally protected URL password, URL expiration, open limits before expiration, ability to set feature activation dates, click tracking, custom vanity identifiers, event dispatching, and soft delete/restore out of the box for your Laravel applications.

Requirements

• PHP 8.1+ (PHP 8.3+ when using Laravel 13)
• Laravel 10.x, 11.x, 12.x, or 13.x

Installation

install the package via composer:

Publish the packages assets.

You can also publish assets by tag.

Run migrations.

Upgrade Guides

Upgrading to v3.x from v2.x

Upgrading to v2.x from v1.x

Usage

Building Short Urls

Finding Existing Short Urls

Deleting & Restoring Short Urls

Getting Click Information

Getting Click Information and Filtering on Ownership

Filter on Outcome

Filter on the Click's YorShortUrl Status

Filtered on YorShortUrl Identifier(s)

Filtered Clicks by UTM parameter(s). These Can be filtered together or individually.

Iterate Through Results With Batches

Putting it all Together

UTM Support

When creating a Short URL, the following UTM parameters are available to attach to the Short URL for advanced tracking of your Short Urls.

• utm_id
• utm_campaign
• utm_source
• utm_medium
• utm_content
• utm_term

UTM information is hidden in the Short URL identifier and clicks are filterable by UTM parameters.

Events

The package dispatches events that you can listen to in your application:

Multi-Domain Support

v3 introduces multi-domain support, allowing you to host short URLs on multiple domains with per-domain configuration.

Enabling Multi-Domain

Set the environment variable or update your config:

Configuration

Building Short URLs for Specific Domains

Domain-Aware Lookups

Same Identifier on Different Domains

With multi-domain enabled, the same identifier can exist on different domains pointing to different URLs:

Routing

Middleware

The package's routes run through the web middleware group by default. Override this to apply your own stack -- rate limiting the redirect endpoint is the common case:

A single middleware may be given as a string. When multi-domain support is enabled, the domain resolution middleware is appended automatically, so you do not need to list it.

Disabling the Default Routes

Set routing.enabled to false to stop the package registering its routes, then wire the redirect action into your own route file:

The urlshortener.attempt.protected route name is required -- the password-protected view posts to it.

Match the prefix you serve. Generated URLs take their prefix from branding.prefix, not from the routes you register, so serving go/{identifier} while branding.prefix is still something/pretty/cool means every link the package hands back points somewhere you do not serve. Set the prefix to match:

Alternatively, build individual URLs with ->withPrefix('go') and list go under routing.additional_prefixes, which is what that setting is for -- it gates withPrefix() validation, and does not affect the default prefix.

Keep the domain middleware when using multi-domain. ResolveDomain is what enforces domains.validate_domain; without it, requests on unconfigured hosts resolve a domain and redirect rather than returning a 404. Include it in your own stack:

Database Connection

By default the package's models and migrations follow your application's default database connection. To isolate them on their own connection, name it in config:

The named connection must exist in your application's config/database.php. Leaving this null preserves the default behaviour.

Security Features

URL Validation

v3 includes built-in URL validation to prevent open redirect and SSRF attacks. This is disabled by default for backwards compatibility, but recommended for new installations.

Protected against:

• javascript: protocol (XSS)
• data: protocol (XSS)
• file: protocol (local file access)
• Private IP ranges (SSRF)
• Cloud metadata endpoints (SSRF)
• Localhost redirects

When DNS private IP checks are enabled, hostnames are resolved during URL creation and any private or reserved resolved IP is rejected. DNS lookup failures or hosts with no IP records are allowed, so add known internal hostnames to blocked_hosts when they should always be rejected.

Rate Limiting for Password-Protected URLs

Brute-force protection is automatically enabled for password-protected short URLs:

After exceeding the maximum attempts, users receive a 429 Too Many Requests response with a Retry-After header.

Environment Variables

Testing

Credits

• Yorda
• All Contributors