#Filament Short URL

A complete Filament v5 admin layer for jeffersongoncalves/laravel-short-url — the headless core package that owns the models, migrations, redirect pipeline, tracking and every business rule. This package duplicates none of that: it's the presentation layer (Resources, Pages and Filament components) built on top of the core's Facade and contracts.

#Compatibility

#What's included

• Short URLs — full CRUD, rule-based targeting (a Rule Builder driven dynamically by the core's FilterTypeRegistry), A/B split, password/warning-page/Safe Browsing, granular tracking toggles, a bidirectional UTM Builder (template application + per-field requirement via short-url.utm.required), pixels.
• Custom Domains — DNS verification (TXT/CNAME), per-registrar instructions.
• Folders, Tags, Pixels — organization and integrations, generated dynamically from the core's own registries (PixelProviderRegistry, etc.) — registering something new in the core makes it show up here without touching this package.
• Import — CSV and Bitly drivers (from the core), with a dry-run preview before importing.
• Metrics — a dedicated page with totals, plan usage vs. limit, and a medium/source/campaign breakdown, rendering the core's StatsPayload/StatsAggregator exclusively (no stats math happens in this package).
• Per-link Statistics — a detail page (ShortUrlResource's statistics action/route) with a date-range filter and widgets for hourly traffic, devices, browsers, operating systems, countries, cities, referrer types, languages, the UTM funnel and A/B variant performance. Hidden together with the Metrics page by hideStatistics().
• Settings — a page whose tabs are generated dynamically from the core's SettingsRepository::schema().
• Every Resource and Page shares the same navigation group (configurable, with a translated fallback).
• pt_BR, en and es translations.

#Screenshots

Screenshot	Light	Dark
Customdomain list
Customdomain create
Customdomain edit
Folder list
Folder create
Folder edit
Pixel list
Pixel create
Pixel edit
Shorturl list
Shorturl create
Shorturl edit
Tag list
Tag create
Tag edit
Import page
Metrics page
Settings page

#Installation

#1. Install the package

composer require jeffersongoncalves/filament-short-url:"^3.0"

This pulls in jeffersongoncalves/laravel-short-url (^2.0) as a dependency.

#2. (Optional) Install dependencies for optional core features

Without them, the corresponding features degrade gracefully — none of these are ever required.

#3. Publish and run the core's migrations

laravel-short-url's migrations ship as .php.stub files inside the package — they are not auto-loaded, they need to be published first.

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

(The tag is short-url-*, not laravel-short-url-* — the core package strips the laravel- prefix from its own name when Spatie Package Tools registers publish tags.)

To publish everything at once (config, migrations, views, translations):

php artisan vendor:publish --provider="JeffersonGoncalves\LaravelShortUrl\LaravelShortUrlServiceProvider"

#4. Register the plugin in your PanelProvider

use JeffersonGoncalves\Filament\ShortUrl\FilamentShortUrlPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentShortUrlPlugin::make()
                ->navigationGroup('Marketing')           // optional — defaults to a translated "Short URL"
                ->navigationLabel('Short Links')          // label for ShortUrlResource specifically
                ->navigationIcon('heroicon-o-link')
                ->navigationSort(50)
                ->wizardForm()                            // opt-in: Create AND Edit pages become a skippable step wizard
                ->hideSecurity()                          // drop the Security section (password/warning page)
                ->hideUtm()                                // drop the UTM Parameters section
                ->hidePixels()                             // drop the Pixels section
                ->hideTargeting()                          // drop rule-based/A-B split targeting — links become single-destination only
                ->hideFolders()                            // removes FolderResource + the folder filter/bulk action
                ->hideTags()                                // removes TagResource + the tags filter/bulk action
                ->authorizeUsing(fn () => auth()->user()->hasRole('admin'))
                ->authorizeSettingsUsing(fn () => auth()->user()->hasRole('admin'))
                ->resources([
                    \JeffersonGoncalves\Filament\ShortUrl\Resources\ShortUrlResource::class,
                    // ...enable only the ones you want; see the full list below
                ])
                ->hideStatistics(),  // removes the Metrics page and the statistics action/column
        ]);
}

For installs that only need "shorten a link" — no security, UTM, pixels or targeting — chain ->simpleMode() instead of the individual hideX() calls above; it turns all of them on at once (pass false to turn them all back off).

#5. Publish Filament's assets

php artisan filament:assets

#6. (Optional) Turn on optional core features via .env

Custom domains are a core feature that is off by default — the corresponding Resource (CustomDomainResource) only shows up in navigation once the core has it enabled:

SHORT_URL_DOMAINS_ENABLED=true

To require UTM parameters on every created link (e.g. track whether a link was shared by SMS, email, an agent, ...):

SHORT_URL_REQUIRED_UTM=utm_medium

This makes the field required in the Filament form itself, and is also enforced by ShortUrlManager on create/update.

#7. (Optional) Publish this package's own config

php artisan vendor:publish --tag="filament-short-url-config"

MetricsPage's slug defaults to short-url-metrics (not Filament's usual metrics-page) to avoid colliding with another jeffersongoncalves/* plugin's own MetricsPage in a host panel that installs both. Override it via config('filament-short-url.metrics_page.slug') or FILAMENT_SHORT_URL_METRICS_PAGE_SLUG in .env.

#Available Resources and Pages

#Authorization

Access to each Resource follows the same three-level chain:

1. Plugin closure — authorizeUsing(). If set, it decides on its own.
2. Policy registered for the corresponding model (via Gate::policy()), if one exists.
3. Default canViewAny() for the Resource (permissive by default).

authorizeSettingsUsing() follows the same fallback for SettingsPage, with an extra middle step: a ShortUrl model Policy with a manageSettings method, if one is registered.

#Testing

composer test        # Pest
composer analyse      # PHPStan (Larastan)
composer format        # Pint

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#Contributing

Please see CONTRIBUTING for details.

#Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

#Credits

• Jefferson Gonçalves
• All Contributors

#License

The MIT License (MIT). Please see License File for more information.