Laravel Sqids

https://github.com/red-explosion/laravel-sqids
Admin
Laravel Sqids is a Laravel package that generates short, collision-free Stripe/YouTube-style IDs for...
Tokens:5,850
Snippets:69
Trust Score:5.5
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Laravel Sqids

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Install the package via Composer and optionally publish the configuration file.

```bash
composer require red-explosion/laravel-sqids

php artisan vendor:publish --tag="sqids-config"
```

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

### Install Laravel Sqids via Composer

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Use this command to add the package to your Laravel project.

```shell
composer require red-explosion/laravel-sqids
```

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

### Implement Custom Table Name Prefix Strategy

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Create a custom prefix strategy by implementing the `Prefix` contract. This example uses the model's table name, truncated to three lowercase characters, as the prefix.

```php
<?php

namespace App\Sqids;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;
use RedExplosion\Sqids\Contracts\Prefix;

// Custom prefix that uses a model's table name
class TablePrefix implements Prefix
{
    public function prefix(string $model): string
    {
        $instance = new $model;
        $table = $instance->getTable();

        return Str::lower(Str::substr($table, 0, 3));
    }
}

```

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

### Run Tests

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Execute the project's test suite using Composer.

```shell
composer test
```

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

### Publish Laravel Sqids Configuration

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Run this Artisan command to publish the configuration file for Laravel Sqids.

```shell
php artisan vendor:publish --tag="sqids-config"
```

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

### Find Model Instance from Sqid (findOrFail)

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Retrieve a model instance using its Sqid, throwing a ModelNotFoundException if no model is found. Requires Sqids to be configured with prefixes.

```php
use RedExplosion\Sqids\Model;

$model = Model::findOrFail('usr_A3EyoEb2TO');
```

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

### Implement Custom Mapped Prefix Strategy

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Define a custom prefix strategy using a mapping array for specific model names. If a model is not found in the map, it falls back to using the first three characters of the model's base name.

```php
<?php

namespace App\Sqids;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Str;
use RedExplosion\Sqids\Contracts\Prefix;

// Custom prefix with abbreviations mapping
class MappedPrefix implements Prefix
{
    protected array $map = [
        'User' => 'usr',
        'Post' => 'post',
        'Comment' => 'cmt',
        'Organization' => 'org',
    ];

    public function prefix(string $model): string
    {
        $basename = class_basename($model);

        return $this->map[$basename] ?? Str::lower(Str::substr($basename, 0, 3));
    }
}

```

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

### Built-in Prefix Strategies

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

The package provides built-in prefix strategies: `ConsonantPrefix` removes vowels (e.g., 'User' -> 'usr'), and `SimplePrefix` uses the first three characters (e.g., 'User' -> 'use').

```php
// Built-in ConsonantPrefix removes vowels: "User" -> "usr", "Customer" -> "cst"
// Built-in SimplePrefix uses first 3 chars: "User" -> "use", "Customer" -> "cus"

```

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

### Find Model Instance from Sqid

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Retrieve a model instance using its Sqid. This method returns null if no model is found for the given Sqid. Requires Sqids to be configured with prefixes.

```php
use RedExplosion\Sqids\Model;

$model = Model::find('usr_A3EyoEb2TO');
```

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

### Find Model by Sqid or Fail

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Use findBySqidOrFail to retrieve a model by its Sqid, throwing a ModelNotFoundException if the model does not exist.

```php
$user = User::findBySqidOrFail('usr_invalid');
```

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

### Register Custom Prefix Strategy in Config

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Configure the Sqids package to use your custom prefix strategy by updating the `prefix_class` option in the `config/sqids.php` file.

```php
// Register in config/sqids.php
return [
    'prefix_class' => App\Sqids\MappedPrefix::class,
];

```

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

### Configure Laravel Sqids

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Customize Sqid generation settings including shuffle key, alphabet, minimum length, blacklisted words, separator, and prefix strategy in the configuration file.

```php
// config/sqids.php
return [
    // Unique key to shuffle the alphabet (defaults to APP_KEY)
    'shuffle_key' => env('APP_KEY'),

    // Characters used in Sqid generation (minimum 3 unique characters)
    'alphabet' => 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789',

    // Minimum length of generated Sqid (excluding prefix and separator)
    'min_length' => 10,

    // Words to exclude from generated Sqids
    'blacklist' => [],

    // Character between prefix and Sqid
    'separator' => '_',

    // Class for generating prefixes (ConsonantPrefix or SimplePrefix)
    'prefix_class' => RedExplosion\Sqids\Prefixes\ConsonantPrefix::class,
];
```

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

### Find Model by Sqid

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Use the `findBySqid` query method to find a model instance by its Sqid. It returns `null` if the model is not found. You can also specify columns to select.

```php
<?php

use App\Models\User;

// Find a user by Sqid (returns null if not found)
$user = User::findBySqid('usr_A3EyoEb2TO');

if ($user) {
    echo "Found user: {$user->name}";
} else {
    echo "User not found";
}

// Select specific columns
$user = User::findBySqid('usr_A3EyoEb2TO', ['id', 'name', 'email']);
```

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

### SqidExists Rule with Query Constraints

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Apply additional query constraints to the SqidExists validation rule, similar to Laravel's Rule::exists, to further refine the model lookup.

```php
use RedExplosion\Sqids\Rules\SqidExists;

$rule = (new SqidExists(Post::class))
    ->where('team_id', $team->id)
    ->withoutTrashed();

$validated = validator(
    ['post' => 'pst_A3EyoEb2TO'],
    ['post' => [$rule]],
)->validate();
```

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

### Encode and Decode Model IDs with Sqids

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Use static methods on the Sqids class to generate, encode, and decode IDs for specific Eloquent models. Ensure the model class is correctly referenced for accurate prefixing and encoding.

```php
<?php

use App\Models\User;
use App\Models\Post;
use RedExplosion\Sqids\Sqids;

// Generate a Sqid for a model instance
$user = User::find(1);
$sqid = Sqids::forModel($user); // "usr_A3EyoEb2TO"

// Encode an ID for a specific model class
$encoded = Sqids::encodeId(User::class, 42); // "A3EyoEb2TO" (without prefix)

// Decode a Sqid back to ID(s)
$decoded = Sqids::decodeId(User::class, 'A3EyoEb2TO'); // [42]

// Get the prefix for a model
$prefix = Sqids::prefixForModel(User::class); // "usr"
$prefix = Sqids::prefixForModel(Post::class); // "pst"

// The encoder is unique per model (different alphabets)
$userEncoder = Sqids::encoder(User::class);
$postEncoder = Sqids::encoder(Post::class);

// Same ID produces different Sqids for different models
$userSqid = Sqids::encodeId(User::class, 1); // e.g., "A3EyoEb2TO"
$postSqid = Sqids::encodeId(Post::class, 1); // e.g., "X7KmpLn9QW"

```

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

### Find Model by Sqid

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Use the findBySqid Eloquent builder method to retrieve a model instance using its Sqid. Returns null if the model is not found.

```php
$user = User::findBySqid('usr_A3EyoEb2TO');
```

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

### Query by Sqid

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Add a WHERE clause to your Eloquent query based on the model's Sqid using the whereSqid method.

```php
$users = User::query()
    ->whereSqid('usr_A3EyoEb2TO')
    ->get();
```

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

### Query by Sqid In Array

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Filter models where the Sqid is present in a given array of Sqids using the whereSqidIn method.

```php
$users = User::query()
    ->whereSqidIn('id', ['usr_A3EyoEb2TO'])
    ->get();
```

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

### Cross-Model Resolution with Model::find

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Use `Model::find` to resolve any model instance from a Sqid string without prior knowledge of the model type. The package automatically scans for models with the `HasSqids` trait and matches based on the Sqid prefix. `Model::findOrFail` can be used to throw an exception if the Sqid is not found.

```php
<?php

use RedExplosion\Sqids\Model;

// Find any model by its Sqid (returns null if not found)
$model = Model::find('usr_A3EyoEb2TO'); // Returns User instance
$model = Model::find('pst_B4FzpGc3UP'); // Returns Post instance
$model = Model::find('cus_C5GaqHd4VQ'); // Returns Customer instance

// Returns null for invalid Sqids
$model = Model::find('invalid_sqid'); // null

// Throw exception if not found
$model = Model::findOrFail('usr_A3EyoEb2TO');

// Useful for polymorphic lookups
public function resolve(string $sqid)
{
    $model = Model::findOrFail($sqid);

    return match (true) {
        $model instanceof User => $this->handleUser($model),
        $model instanceof Post => $this->handlePost($model),
        default => abort(404),
    };
}

// Search endpoint that works across multiple model types
Route::get('/search/{sqid}', function (string $sqid) {
    $result = Model::find($sqid);

    if (!$result) {
        return response()->json(['error' => 'Not found'], 404);
    }

    return response()->json([
        'type' => class_basename($result),
        'data' => $result,
    ]);
});

```

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

### Query with Sqid WHERE Clause

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Use the `whereSqid` query method to add a condition to your query that matches a Sqid to the model's primary key. It can be combined with other query conditions.

```php
<?php

use App\Models\User;

// Basic usage - get users matching the Sqid
$users = User::query()
    ->whereSqid('usr_A3EyoEb2TO')
    ->get();

// Combine with other query conditions
$user = User::query()
    ->whereSqid('usr_A3EyoEb2TO')
    ->where('is_active', true)
    ->first();

// Use in a scope or complex query
$activeUsers = User::query()
    ->whereSqid('usr_A3EyoEb2TO')
    ->with(['posts', 'comments'])
    ->firstOrFail();
```

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

### Route Model Binding with Laravel Sqids

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Integrate Sqids with Laravel's route model binding. Ensure your models are configured to use Sqids for automatic ID conversion in routes.

```php
Route::get('users/{user}', function (User $user) {
    return "Hello $user->name";
});
```

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

### Enable Sqids on Eloquent Model

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Add the HasSqids trait to your Eloquent model to enable Sqid functionality. This automatically appends a `sqid` attribute, enables route model binding, and provides `keyFromSqid` for decoding.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use RedExplosion\Sqids\Concerns\HasSqids;

class User extends Model
{
    use HasSqids;

    // Optional: Override the default prefix
    protected string $sqidPrefix = 'user';
}

// Usage examples
$user = User::find(1);

// Access the Sqid (auto-generated from primary key)
$sqid = $user->sqid; // "usr_A3EyoEb2TO" (or "user_A3EyoEb2TO" with custom prefix)

// Decode a Sqid back to the primary key
$id = User::keyFromSqid('usr_A3EyoEb2TO'); // 1

// The sqid attribute is automatically appended to JSON/array output
$user->toArray(); // ['id' => 1, 'name' => 'John', ..., 'sqid' => 'usr_A3EyoEb2TO']
```

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

### Filter Models with whereSqidIn

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Use `whereSqidIn` to filter models where a specified column matches any of the decoded Sqid values in a given array. This is useful for retrieving multiple records based on their Sqid identifiers.

```php
<?php

use App\Models\User;

// Get all users matching the array of Sqids
$users = User::query()
    ->whereSqidIn('id', [
        'usr_A3EyoEb2TO',
        'usr_B4FzpGc3UP',
        'usr_C5GaqHd4VQ',
    ])
    ->get();

// Combine with eager loading
$users = User::query()
    ->whereSqidIn('id', $sqidArray)
    ->with('profile')
    ->orderBy('created_at', 'desc')
    ->get();

```

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

### Validate Sqid Exists Rule

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Use the SqidExists validation rule in form requests to ensure a provided Sqid corresponds to an existing model. This rule decodes the Sqid and checks for the model's existence.

```php
use RedExplosion\Sqids\Rules\SqidExists;

$validated = validator(
    ['customer_id' => 'cus_A3EyoEb2TO'],
    ['customer_id' => [new SqidExists(Customer::class)]],
)->validate();
```

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

### Set Custom Sqid Prefix

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Override the default Sqid prefix by defining the $sqidPrefix property on your model. This is useful for distinguishing IDs across different model types.

```php
use RedExplosion\Sqids\Concerns\HasSqids;

class User extends Authenticatable
{
    use HasSqids;
    
    protected string $sqidPrefix = 'user';
}

$user = User::first();
$sqid = $user->sqid; // user_A3EyoEb2TO
```

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

### Query by Sqid Not In Array

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Filter models where the Sqid is not present in a given array of Sqids using the whereSqidNotIn method.

```php
$users = User::query()
    ->whereSqidNotIn('id', ['usr_A3EyoEb2TO'])
    ->get();
```

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

### Filter Models with whereSqidNotIn

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Use `whereSqidNotIn` to exclude models where a specified column matches any of the decoded Sqid values. This method is helpful for filtering out specific records, such as excluding the current user.

```php
<?php

use App\Models\User;

// Get all users except those with the specified Sqids
$users = User::query()
    ->whereSqidNotIn('id', [
        'usr_A3EyoEb2TO',
        'usr_B4FzpGc3UP',
    ])
    ->get();

// Useful for excluding specific records
$otherUsers = User::query()
    ->whereSqidNotIn('id', [$currentUser->sqid])
    ->where('team_id', $currentUser->team_id)
    ->get();

```

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

### SqidExists Validation Rule

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Use the `SqidExists` validation rule in form requests to ensure a Sqid corresponds to an existing record in a specified model. It supports additional query constraints like `where` and `withoutTrashed` for precise validation.

```php
<?php

use App\Models\Customer;
use App\Models\Post;
use RedExplosion\Sqids\Rules\SqidExists;

// Basic validation
$validated = validator(
    ['customer_id' => 'cus_A3EyoEb2TO'],
    ['customer_id' => ['required', new SqidExists(Customer::class)]],
)->validate();

// With query constraints
$rule = (new SqidExists(Post::class))
    ->where('team_id', $team->id)
    ->where('status', 'published')
    ->withoutTrashed();

$validated = validator(
    ['post' => 'pst_A3EyoEb2TO'],
    ['post' => ['required', $rule]],
)->validate();

// In a Form Request class
class StoreCommentRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'post_id' => [
                'required',
                (new SqidExists(Post::class))
                    ->where('user_id', auth()->id())
                    ->withoutTrashed(),
            ],
            'body' => ['required', 'string', 'max:1000'],
        ];
    }
}

// Available constraint methods:
// ->where($column, $value)
// ->whereNot($column, $value)
// ->whereNull($column)
// ->whereNotNull($column)
// ->whereIn($column, $values)
// ->whereNotIn($column, $values)
// ->withoutTrashed()
// ->onlyTrashed()

```

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

### Route Model Binding with Sqids

Source: https://context7.com/red-explosion/laravel-sqids/llms.txt

Laravel Sqids enables automatic route model binding. Type-hint your model in route definitions or controller methods, and Laravel will resolve the model from the Sqid in the URL. This works seamlessly with standard, resource, and API routes.

```php
<?php

use App\Models\User;
use Illuminate\Support\Facades\Route;

// routes/web.php
Route::get('/users/{user}', function (User $user) {
    return "Hello {$user->name}";
});

// GET /users/usr_A3EyoEb2TO -> Resolves to User with ID 1

// In a controller
class UserController extends Controller
{
    public function show(User $user)
    {
        // $user is automatically resolved from the Sqid in the URL
        return view('users.show', compact('user'));
    }

    public function update(Request $request, User $user)
    {
        $user->update($request->validated());

        return redirect()->route('users.show', $user);
    }
}

// Resource routes work automatically
Route::resource('users', UserController::class);

// API routes
Route::get('/api/users/{user}', function (User $user) {
    return response()->json($user);
});

```

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

### Use HasSqids Trait in Eloquent Model

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Add the HasSqids trait to your Eloquent model to enable Sqid generation. Ensure your model's primary key is an integer.

```php
use RedExplosion\Sqids\Concerns\HasSqids;

class User extends Authenticatable
{
    use HasSqids;
}
```

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

### Access Sqid Attribute

Source: https://github.com/red-explosion/laravel-sqids/blob/2.x/README.md

Once the HasSqids trait is used, you can access the generated Sqid via the 'sqid' attribute on model instances.

```php
$user = User::first();

$sqid = $user->sqid; // usr_A3EyoEb2TO
```
Tokens:
Raw