README

Filament Sqids is a Laravel package that automatically encodes and decodes model IDs using sqids/sqids. By replacing numerical IDs with obfuscated Sqids, this package not only improves the aesthetics of your URLs but also provides an extra layer of security.

Filament Sqids

Features

Automatic Sqids Encoding: Transform model IDs in your URLs (e.g. /admin/users/1/edit becomes /admin/users/86Rf07xd4z/edit).
Automatic Sqids Decoding: Middleware decodes Sqids back to real IDs when processing requests.
Model Trait (HasSqids): Easily apply Sqids to any Filament model.
Filament Plugin (SqidsPlugin.php): Seamlessly integrate with Filament, overriding resource routes and actions.
Customisable Sqids Config: Configure custom minimum length and alphabet via filament-sqids.php.
Blade Directive (@sqids($model)): Helper directive for generating Sqids in your Blade templates.
Artisan Command (install:sqids): Simplifies setup by publishing configuration files and verifying dependencies.

Installation

Install the package via Composer:

composer require qopiku/filament-sqids

If you wish to customise the configuration, run the install command:

php artisan install:filament-sqids

This command will publish the configuration file (config/filament-sqids.php) to your Laravel application.

Configuration

After installation, you can adjust your settings in the config/filament-sqids.php file. You may set:

min_length: The minimum length for the generated Sqids.
alphabet: The alphabet used to generate the Sqids.

Usage

Using the Model Trait

Simply include the HasSqids trait in your model to enable Sqids functionality:

use Qopiku\FilamentSqids\Traits\HasSqids;

class User extends Authenticatable
{
    use HasSqids;

    // ...
}

You can then retrieve the Sqids for a model instance:

$user = User::find(1);
echo $user->getSqids();

You can query by Sqids for a model:

$user = User::findSqids($sqids);
$users = User::whereSqids($sqids)->get();

Blade Directive

In your Blade templates, generate a Sqids easily with the provided directive:

@sqids($user)

This will output the encoded ID of the model.

Setup the Middleware

Middleware ensures that incoming requests with Sqids are automatically decoded into their corresponding numerical IDs. You can set it up in two ways:

Via Panels

To apply the middleware globally to a Filament panel, include it in the panel's middleware stack:

use Filament\Panel;
use Filament\PanelProvider;
use Qopiku\FilamentSqids\Middleware\FilamentSqidsMiddleware;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->middleware([
                FilamentSqidsMiddleware::class, // Decodes Sqids for all routes in this panel
                // ...existing code...
            ]);
    }
}

Via Specific Resources

If you want to apply the middleware to specific resources only, you can define it in the resource's $routeMiddleware property:

use Filament\Resources\Resource;

class UserResource extends Resource
{
    public static array|string $routeMiddleware = [
        'filament-sqids', // Ensures Sqids are decoded for this resource's routes
    ];
}

Testing

The package includes a suite of tests to cover its key functionality:

Feature Tests: Validate that URLs are correctly rewritten and that routes work as expected.
Unit Tests: Ensure that the SqidsManager, middleware, and helper functions behave correctly.

To run the tests, simply execute:

vendor/bin/phpunit

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests if you have suggestions or improvements.

Licence

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

Enjoy building secure and aesthetically pleasing URLs with Filament Sqids!

qopiku / filament-sqids

Maintainers

Details