README

A Laravel/Filament v4 package that provides comprehensive URL redirect management with automatic redirect handling, hit tracking, loop detection, and a powerful Filament admin panel for managing redirects.

Features

Automatic Redirects: Middleware automatically handles URL redirects (301 & 302)
Hit Tracking: Track redirect usage with hit count and last hit timestamp
Loop Detection: Prevents creating circular redirect loops (A → B → A)
Caching: Built-in caching support for optimal performance
Filament Resource: Full-featured admin panel with inline create/edit modals
Import/Export: Bulk operations via CSV import and export
Validation: Prevents duplicate old_urls and validates redirect chains

Installation

You can install the package via composer:

composer require smart-cms/redirects

Full package install:

php artisan redirects:install

Or you can publish and run the migrations with:

php artisan vendor:publish --tag="redirects-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="redirects-config"

Usage

Register the Filament Plugin

Add the plugin to your Filament panel provider:

use SmartCms\Redirects\RedirectsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            RedirectsPlugin::make(),
            // Or with custom navigation group:
            RedirectsPlugin::make('Settings'),
        ]);
}

Middleware

The redirect middleware is automatically registered to the web middleware group. When a user visits a URL that matches a redirect's old_url, they will be automatically redirected to the new_url with the specified status code (301 or 302).

Creating Redirects Programmatically

use SmartCms\Redirects\Models\Redirect;

// Create a permanent redirect (301)
Redirect::create([
    'old_url' => '/old-page',
    'new_url' => '/new-page',
    'status_code' => 301,
]);

// Create a temporary redirect (302)
Redirect::create([
    'old_url' => '/temporary',
    'new_url' => '/new-location',
    'status_code' => 302,
]);

Hit Tracking

The package automatically tracks how many times each redirect is used:

$redirect = Redirect::find(1);

echo $redirect->hit_count;      // Number of times this redirect was used
echo $redirect->last_hit_at;    // Carbon instance of last hit

// Find popular redirects
$popular = Redirect::where('hit_count', '>', 100)->get();

// Find recently used redirects
$recent = Redirect::where('last_hit_at', '>', now()->subDays(7))->get();

// Find unused redirects
$unused = Redirect::where('hit_count', 0)
    ->whereNull('last_hit_at')
    ->get();

Loop Detection

The package prevents creating circular redirect loops:

// This will be prevented:
Redirect::create(['old_url' => '/page', 'new_url' => '/page']); // Self-loop

// If you have: /a → /b
// This will be prevented: /b → /a (creates circular loop)

// The validation also detects complex loops:
// /a → /b → /c → /a (prevents closing the loop)

Import/Export

Use the Filament admin panel to:

Export All: Export all redirects to CSV via the header "Export CSV" button
Export Selected: Select specific redirects and use the bulk action "Export Selected"
Import CSV: Click "Import CSV" and upload a CSV file with columns: old_url, new_url, status_code

CSV Format:

old_url,new_url,status_code,hit_count
/old-page,/new-page,301,0
/temporary,/destination,302,0

Caching

Redirects are cached for performance. The cache is automatically cleared when:

A redirect is created
A redirect is updated
A redirect is deleted

To manually clear the cache:

Redirect::clearCache();

To disable caching:

// In config/redirects.php
'cache' => [
    'enabled' => false,
],

Testing

composer test

Credits

License

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

smart-cms / redirects

Maintainers

Details