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.

Table of Contents

• Filament Sqids
  • Table of Contents
  • Features
  • Installation
  • Configuration
  • Usage
    • Using the Model Trait
    • Blade Directive
    • Setup the Middleware
      • Via Panels
      • Via Specific Resources
  • Testing
  • Contributing
  • Licence

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): Seamlessly integrate with Filament panels via $panel->plugin(SqidsPlugin::make()).
• 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.

Using the Plugin (Recommended)

The simplest way to enable Sqids in your Filament panel is to use the SqidsPlugin:

use Filament\Panel;
use Filament\PanelProvider;
use Qopiku\FilamentSqids\Plugin\SqidsPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->plugin(SqidsPlugin::make());
    }
}

Setup the Middleware Manually

If you prefer not to use the plugin system, you can apply the middleware directly:

Via Panels

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

Apply the middleware to specific resources only:

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!