Laravel Short URL

https://github.com/jeffersongoncalves/laravel-short-url
Admin
Laravel Short URL is a headless URL-shortening engine for Laravel providing link creation, redirect...
Tokens:9,660
Snippets:67
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies with composer install

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/AGENTS.md

Installs the project dependencies. Run this after cloning the repository.

```bash
composer install
```

--------------------------------

### Create, resolve, and get full URL with ShortUrl facade

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Shows the main ShortUrl facade methods: create with an array, fluent creation with key, expiry, max visits, and password, resolving by key, and getting the full URL. Redirecting to GET /{urlKey} requires no extra code.

```php
use JeffersonGoncalves\LaravelShortUrl\Facades\ShortUrl;

// Create
$link = ShortUrl::create(['destination_url' => 'https://example.com/product']);

// Fluent
$link = ShortUrl::destination('https://example.com/product')
    ->key('promo25')
    ->expiresAt(now()->addDays(30))
    ->maxVisits(1000)
    ->password('secret')
    ->create();

// Resolve
$link = ShortUrl::resolve('promo25');

// The ready-to-share URL — custom domain when set, otherwise the app's own host
$link->fullUrl(); // https://short.test/promo25
```

--------------------------------

### Install and publish Laravel Short URL package

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/resources/boost/skills/short-url-development/SKILL.md

Install the package and publish its configuration, migrations, and translations, then run migrations. All package tables use the `short_url_` prefix by default, configurable via `table_prefix`.

```bash
composer require jeffersongoncalves/laravel-short-url
php artisan vendor:publish --tag="short-url-config"
php artisan vendor:publish --tag="short-url-migrations"
php artisan vendor:publish --tag="short-url-translations"
php artisan migrate
```

--------------------------------

### Install laravel-short-url with Composer

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Install the package via Composer. Requires PHP 8.3+ and Laravel 12 or 13.

```bash
composer require jeffersongoncalves/laravel-short-url
```

--------------------------------

### Install endroid/qr-code for QR support

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Installs the optional endroid/qr-code package (^6.0) required for QR code generation. Without it, QR calls throw QrCodeGeneratorMissing.

```bash
composer require endroid/qr-code
```

--------------------------------

### Create short URLs with split and rules destination types

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Shows how to create a short URL with destination_type 'split' for weighted A/B rotation and 'rules' for conditional targeting. The split example uses rotation_variants with weights and labels; the rules example uses targeting_rules with conditions (default AND, wrap in ['or' => [...]] for OR) and a destination that can be a nested split array. Conditions support types like device, country, language, and more.

```php
// Weighted A/B rotation
ShortUrl::create([
    'destination_url' => 'https://example.com/base', // fallback
    'destination_type' => 'split',
    'rotation_variants' => [
        ['url' => 'https://a.test', 'weight' => 50, 'label' => 'A'],
        ['url' => 'https://b.test', 'weight' => 50, 'label' => 'B'],
    ],
]);
```

```php
// Conditional targeting, evaluated per request
ShortUrl::create([
    'destination_url' => 'https://example.com/base', // used when no rule matches
    'destination_type' => 'rules',
    'targeting_rules' => [
        [
            'conditions' => [
                ['type' => 'country', 'value' => 'FR'],
                ['type' => 'device', 'value' => 'mobile'],
            ],
            'destination' => 'https://example.com/france-mobile',
        ],
    ],
]);
```

--------------------------------

### Publish config, migrations, and translations

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Publish the package's config, migrations, and translations, then run the database migrations.

```bash
php artisan vendor:publish --tag="short-url-config"
php artisan vendor:publish --tag="short-url-migrations"
php artisan vendor:publish --tag="short-url-translations"
php artisan migrate
```

--------------------------------

### Run test, analyse, and format commands

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/AGENTS.md

Lists the main Composer commands for testing, coverage, static analysis, and formatting. Run all three (test, analyse, format) before considering a change done, as CI enforces all three on every push.

```bash
composer test           # Pest test suite
composer test-coverage  # Pest with coverage
composer analyse        # PHPStan (Larastan) level 6
composer format          # Pint (Laravel preset)
```

--------------------------------

### Run tests, analysis, and formatting with Composer scripts

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Run the package's test suite with Pest, static analysis with PHPStan (Larastan) at level 6, and code formatting with Pint. CI runs these against PHP 8.4 / Laravel 13 on SQLite, MySQL, and PostgreSQL.

```bash
composer test     # Pest
composer analyse  # PHPStan (Larastan) level 6
composer format   # Pint
```

--------------------------------

### Create and resolve short links with ShortUrl facade

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/resources/boost/skills/short-url-development/SKILL.md

Create short links using either a plain array or the fluent builder, resolve by key, and generate the full shareable URL. The builder supports explicit keys, expiration, visit limits, single-use, password protection, redirect status codes, and query parameter forwarding.

```php
use JeffersonGoncalves\LaravelShortUrl\Facades\ShortUrl;

// Plain array
$link = ShortUrl::create(['destination_url' => 'https://example.com/product']);

// Fluent builder — ShortUrlBuilder
$link = ShortUrl::destination('https://example.com/product')
    ->key('promo25')                       // explicit key, otherwise Base62-generated
    ->title('Spring promo')
    ->expiresAt(now()->addDays(30))
    ->maxVisits(1000)
    ->singleUse()                          // disables after first visit
    ->password('secret')                   // bcrypt-hashed, never stored plain
    ->redirectStatusCode(301)
    ->forwardQueryParams()
    ->create();

// Resolve by key (used internally by the redirect pipeline too)
$link = ShortUrl::resolve('promo25');

// Ready-to-share URL — custom domain when set, otherwise the app's own host
$link->fullUrl();
```

--------------------------------

### List of swappable contracts and registries for extending the package

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/resources/boost/skills/short-url-development/SKILL.md

Lists the interfaces under src/Contracts/ that can be rebound in a service provider, and the registries that support extend() for multiple drivers.

```php
VisitRepository, GeoIpDriver, VpnDetectionDriver, AnalyticsDriver,
SafeBrowsingChecker, StatsAggregator, TargetingResolver,
DnsVerifier, SettingsRepository, ImporterDriver,
ConversionApiDispatcher, TenantResolver, PlanResolver, CustomDomainResolver

// Registries (extend() instead of rebind — multiple drivers coexist)
FilterTypeRegistry, AnalyticsDriverRegistry,
PixelProviderRegistry, ImporterDriverRegistry
```

--------------------------------

### Create ShortUrl with UTM template and explicit UTM values

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Creates a tenant-scoped UtmTemplate and uses it to build a ShortUrl with UTM parameters. Explicit utm() values override template values; unset fields are filled from the template. Requires the Laravel Short URL package.

```php
use JeffersonGoncalves\LaravelShortUrl\Models\UtmTemplate;

$campaign = UtmTemplate::create(['name' => 'Spring SMS', 'utm_medium' => 'sms', 'utm_campaign' => 'spring-sale']);

$link = ShortUrl::destination('https://example.com/product')
    ->utmTemplate($campaign->id)   // fills in unset utm_* fields from the template
    ->utm(['utm_source' => 'agent-42']) // explicit values always win over the template
    ->create();
```

--------------------------------

### Generate QR codes for ShortUrl

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Generates QR codes for a ShortUrl's fullUrl() in SVG, PNG, or data URI formats. Requires the endroid/qr-code package; otherwise throws QrCodeGeneratorMissing. Does not affect link creation or redirects.

```php
$link->qrCode()->svg();                                // string
$link->qrCode()->png();                                // string
$link->qrCode(size: 400, margin: 20)->dataUri();        // data:image/png;base64,...
$link->qrCode()->dataUri('svg');                        // data:image/svg+xml;base64,...
```

--------------------------------

### Batch resolve multiple URLs with resolveMany()

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Batch-resolves multiple destination URLs in one call. Dedupes input, performs a single batched cache read and one whereIn() query for cache misses, and only creates new links for genuinely new destinations. Destinations that fail to mint a key (e.g., plan limit, missing UTM) fall back to themselves in the result.

```php
$links = ShortUrl::resolveMany([
    'https://example.com/product-a',
    'https://example.com/product-b',
]);

// ['https://example.com/product-a' => 'https://short.test/aBc1234', 'https://example.com/product-b' => 'https://short.test/xYz9876']
```

--------------------------------

### Split (weighted A/B) destination

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/resources/boost/skills/short-url-development/SKILL.md

Creates a short URL with a split destination type, using weighted variants for A/B testing. The `destination_url` serves as a fallback. Each variant specifies a URL, weight, and label.

```php
ShortUrl::create([
    'destination_url' => 'https://example.com/base', // fallback
    'destination_type' => 'split',
    'rotation_variants' => [
        ['url' => 'https://a.test', 'weight' => 50, 'label' => 'A'],
        ['url' => 'https://b.test', 'weight' => 50, 'label' => 'B'],
    ],
]);
```

--------------------------------

### Redirect pipeline stages

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/resources/boost/skills/short-url-development/SKILL.md

Shows the ordered stages of the redirect pipeline. Each stage is an invokable class under src/Pipeline/Stages/ and can short-circuit by returning a Response directly. Add custom stages by extending RedirectPipeline's stage array via the container; do not bypass the pipeline with a custom redirect controller.

```text
ResolveHost → RateLimit → ResolveShortUrl(cache) → DetectBot → DetectVpnProxy
→ CheckAvailability → RequirePassword → ShowWarning → ResolveDestination
→ BuildFinalUrl → RenderInterstitial → Respond → DispatchTracking
```

--------------------------------

### Tagging a link via a UTM template

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/resources/boost/skills/short-url-development/SKILL.md

Use this snippet to create a ShortUrl with campaign tagging via a reusable UtmTemplate. The utmTemplate() method fills in unset utm_* fields from the template, while explicit utm() values always override them. The customDomain() method attaches a custom domain by its ID.

```php
use JeffersonGoncalves\LaravelShortUrl\Models\UtmTemplate;

$campaign = UtmTemplate::create(['name' => 'Spring SMS', 'utm_medium' => 'sms']);

$link = ShortUrl::destination('https://example.com/product')
    ->utmTemplate($campaign->id)          // fills in unset utm_* fields
    ->utm(['utm_source' => 'agent-42'])   // explicit values always win
    ->customDomain($domain->id)
    ->create();
```

--------------------------------

### Bind CustomDomainResolver for custom domain resolution

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Bind Contracts\CustomDomainResolver to resolve custom domains from your own domain data instead of registering them in short_url_custom_domains. The returned CustomDomain need not be persisted; when bound, Pipeline\Stages\ResolveHost uses it whenever domains.enabled is true.

```php
// App\Providers\AppServiceProvider

use JeffersonGoncalves\LaravelShortUrl\Contracts\CustomDomainResolver;
use JeffersonGoncalves\LaravelShortUrl\Models\CustomDomain;

public function register(): void
{
    $this->app->bind(CustomDomainResolver::class, function () {
        return new class implements CustomDomainResolver
        {
            public function resolve(string $host): ?CustomDomain
            {
                $account = \App\Models\Account::whereDomain($host)->first();

                if (! $account) {
                    return null;
                }

                return (new CustomDomain)->forceFill([
                    'id' => $account->id,
                    'tenant_id' => $account->id,
                    'is_verified' => true,
                ]);
            }
        };
    });
}
```

--------------------------------

### Query aggregated stats with StatsAggregator

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/resources/boost/skills/short-url-development/SKILL.md

Shows how to query aggregated stats via the StatsAggregator contract. Use for() for a single link and forShortUrls() for a cross-link breakdown; the caller must resolve which links belong in the set. Prefer this over querying short_url_visits or short_url_daily_stats directly, as raw rows are pruned by short-url:aggregate-and-prune.

```php
use JeffersonGoncalves\LaravelShortUrl\Contracts\StatsAggregator;

// Single link
$stats = app(StatsAggregator::class)->for($shortUrl)->between(now()->subDays(7), now())->get();

// Across a set of links (a folder, a tag, "everything this tenant owns") —
// for a dashboard's global breakdown. Resolving *which* links belong in the
// set is always the caller's job via ShortUrl's own tenant-scoped query;
// StatsAggregator only does the aggregation math, never link selection.
$ids = ShortUrl::query()->where('folder_id', $folder->id)->pluck('id')->all();
$stats = app(StatsAggregator::class)->forShortUrls($ids)->between(now()->subDays(7), now())->get();
```

--------------------------------

### Bind TenantResolver for custom multi-tenancy

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/README.md

Bind Contracts\TenantResolver in AppServiceProvider to use your own tenancy instead of stancl/tenancy. The config enables tenancy. TenantResolver is checked before stancl's tenant() helper and the static current_tenant_id fallback.

```php
// App\Providers\AppServiceProvider

use JeffersonGoncalves\LaravelShortUrl\Contracts\TenantResolver;

public function register(): void
{
    $this->app->bind(TenantResolver::class, function () {
        return new class implements TenantResolver
        {
            public function resolve(): int|string|null
            {
                return \App\Models\Tenant::current()?->id;
            }
        };
    });
}
```

```php
// config/short-url.php
'tenancy' => ['enabled' => true],
```

--------------------------------

### Rules (conditional targeting) destination

Source: https://github.com/jeffersongoncalves/laravel-short-url/blob/master/resources/boost/skills/short-url-development/SKILL.md

Creates a short URL with a rules destination type, using targeting rules to conditionally redirect based on request attributes. The `destination_url` is used when no rule matches. Conditions default to AND; wrap in `['or' => [...]]` for OR groups.

```php
ShortUrl::create([
    'destination_url' => 'https://example.com/base', // used when no rule matches
    'destination_type' => 'rules',
    'targeting_rules' => [
        [
            'conditions' => [
                ['type' => 'country', 'value' => 'FR'],
                ['type' => 'device', 'value' => 'mobile'],
            ],
            // conditions default to AND; wrap in ['or' => [...]] for OR groups
            'destination' => 'https://example.com/france-mobile',
        ],
    ],
]);
```
Tokens:
Raw