Laravel Prefixed IDs

https://github.com/spatie/laravel-prefixed-ids
Admin
Laravel Prefixed IDs is a Laravel package that generates friendly prefixed unique identifiers for...
Tokens:5,322
Snippets:38
Trust Score:10
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Installing Spatie Laravel Prefixed IDs via Composer

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Installs the spatie/laravel-prefixed-ids package into your Laravel project using Composer. This command downloads and integrates the package dependencies.

```bash
composer require spatie/laravel-prefixed-ids
```

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

### Get Model Class Name from Prefixed ID using PrefixedIds::getModelClass()

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

The `PrefixedIds::getModelClass()` method returns the fully qualified model class name associated with a given prefixed ID without querying the database. It returns `null` for unknown prefixes. This is useful for validation, routing, or conditional logic based on the resource type.

```php
<?php

use Spatie\PrefixedIds\PrefixedIds;

// Determine the model type from a prefixed ID
$modelClass = PrefixedIds::getModelClass('user_550e8400e29b41d4a716446655440000');
echo $modelClass; // Output: App\Models\User

$modelClass = PrefixedIds::getModelClass('order_6ba7b8109dad11d180b400c04fd430c8');
echo $modelClass; // Output: App\Models\Order

// Returns null for unknown prefixes
$unknown = PrefixedIds::getModelClass('invalid_prefix_abc');
var_dump($unknown);

// Useful for request validation
class ResourceRequest extends FormRequest
{
    public function rules()
    {
        $modelClass = PrefixedIds::getModelClass($this->resource_id);

        if ($modelClass === User::class) {
            return ['action' => 'required|in:activate,deactivate'];
        }

        if ($modelClass === Order::class) {
            return ['action' => 'required|in:ship,cancel,refund'];
        }

        throw new ValidationException('Unknown resource type');
    }
}

```

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

### Run package tests

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Execute the test suite for the package using the composer test command.

```bash
composer test
```

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

### Publish and Customize Prefixed IDs Configuration in Laravel

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

This command publishes the configuration file for the Spatie Laravel Prefixed IDs package, allowing you to customize the attribute name used for storing prefixed IDs. After publishing, you can modify the `config/prefixed-ids.php` file and update your database migrations and model attribute access accordingly.

```bash
php artisan vendor:publish --provider="Spatie\PrefixedIds\PrefixedIdsServiceProvider" --tag="prefixed-ids-config"
```

```php
<?php

// config/prefixed-ids.php
return [
    /*
     * The attribute name used to store prefixed ids on a model.
     * Change this if you want to use a different column name.
     */
    'prefixed_id_attribute_name' => 'prefixed_id',

    // Example: use 'public_id' instead
    // 'prefixed_id_attribute_name' => 'public_id',
];

// If you change the attribute name, update your migration accordingly:
Schema::table('users', function (Blueprint $table) {
    $table->string('public_id')->nullable()->unique();
});

// And access it via the new attribute:
$user = User::create(['name' => 'John']);
echo $user->public_id; // Output: user_550e8400...
```

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

### Find Model by Prefixed ID or Throw Exception

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

Employs the `findByPrefixedIdOrFail()` static method to find a model by its prefixed ID. If the model is not found, it throws a `NoPrefixedModelFound` exception, suitable for controller actions.

```php
<?php

use App\Models\User;
use Spatie\PrefixedIds\Exceptions\NoPrefixedModelFound;

// In a controller
class UserController extends Controller
{
    public function show(string $prefixedId)
    {
        try {
            $user = User::findByPrefixedIdOrFail($prefixedId);

            return response()->json([
                'id' => $user->prefixed_id,
                'name' => $user->name,
                'email' => $user->email,
            ]);
        } catch (NoPrefixedModelFound $e) {
            return response()->json([
                'error' => 'User not found',
                'message' => $e->getMessage(),
            ], 404);
        }
    }
}

// Usage:
// GET /api/users/user_550e8400e29b41d4a716446655440000
// Response: {"id": "user_550e8400...", "name": "John Doe", "email": "john@example.com"}

// GET /api/users/user_invalid
// Response: {"error": "User not found", "message": "Could not find a prefixed model `user_invalid`"}
```

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

### Register Models and Prefixes in Service Provider

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

Registers Eloquent models with their corresponding prefixes in a service provider. This configuration step is crucial for the `HasPrefixedId` trait to function correctly.

```php
<?php

namespace App\Providers;

use App\Models\Order;
use App\Models\Product;
use App\Models\User;
use Illuminate\Support\ServiceProvider;
use Spatie\PrefixedIds\PrefixedIds;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        PrefixedIds::registerModels([
            'user_' => User::class,
            'order_' => Order::class,
            'prod_' => Product::class,
        ]);
    }
}

// Now when you create models, they automatically get prefixed IDs:
$user = User::create(['name' => 'John Doe', 'email' => 'john@example.com']);
echo $user->prefixed_id; // Output: user_550e8400e29b41d4a716446655440000

$order = Order::create(['total' => 99.99]);
echo $order->prefixed_id; // Output: order_6ba7b8109dad11d180b400c04fd430c8

$product = Product::create(['name' => 'Widget']);
echo $product->prefixed_id; // Output: prod_f47ac10b58cc4372a5670e02b2c3d479
```

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

### Implement Route Model Binding with Prefixed IDs in Laravel

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

This snippet demonstrates how to use prefixed IDs for route model binding in Laravel. By implementing the `getRouteKeyName` method on your Eloquent model and using the `HasPrefixedId` concern, Laravel will automatically resolve models using their prefixed IDs in routes. This improves API clarity by including a type identifier in the URL.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\PrefixedIds\Models\Concerns\HasPrefixedId;

class User extends Model
{
    use HasPrefixedId;

    public function getRouteKeyName()
    {
        return 'prefixed_id';
    }
}

// In routes/api.php
Route::get('/users/{user}', function (User $user) {
    return response()->json([
        'id' => $user->prefixed_id,
        'name' => $user->name,
    ]);
});

// Example Usage:
// GET /api/users/user_550e8400e29b41d4a716446655440000
// Response: {"id": "user_550e8400...", "name": "John Doe"}
```

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

### Find Model by Prefixed ID

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

Utilizes the `findByPrefixedId()` static method on Eloquent models to retrieve a model instance using its unique prefixed ID. Returns the model or `null` if not found.

```php
<?php

use App\Models\User;

// Find a user by their prefixed ID
$user = User::findByPrefixedId('user_550e8400e29b41d4a716446655440000');

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

// Returns null for non-existing IDs
$notFound = User::findByPrefixedId('user_nonexistent');
var_dump($notFound); // Output: NULL
```

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

### Find Models by Prefixed ID or Throw Exception using PrefixedIds::findOrFail()

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

The `PrefixedIds::findOrFail()` method is similar to `find()` but throws a `NoPrefixedModelFound` exception if the model cannot be located. This is ideal for API endpoints or scenarios where a missing resource should result in an error response.

```php
<?php

use Spatie\PrefixedIds\Exceptions\NoPrefixedModelFound;
use Spatie\PrefixedIds\PrefixedIds;

// API endpoint that handles any resource type
class ResourceController extends Controller
{
    public function show(string $prefixedId)
    {
        try {
            $model = PrefixedIds::findOrFail($prefixedId);

            return response()->json([
                'type' => class_basename($model),
                'id' => $model->prefixed_id,
                'data' => $model->toArray(),
            ]);
        } catch (NoPrefixedModelFound $e) {
            return response()->json([
                'error' => 'Resource not found',
            ], 404);
        }
    }
}

// Works with any registered model type:
// GET /api/resources/user_abc123 -> Returns User data
// GET /api/resources/order_xyz789 -> Returns Order data
// GET /api/resources/invalid_id -> Returns 404

```

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

### Customize Unique ID Generation with PrefixedIds::generateUniqueIdUsing()

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

The `PrefixedIds::generateUniqueIdUsing()` method allows you to define a custom algorithm for generating the unique part of the prefixed ID. You can provide a closure to return shorter, sequential, or any custom ID format. Passing `null` resets it to the default UUID v4 generation.

```php
<?php

use Spatie\PrefixedIds\PrefixedIds;
use Illuminate\Support\Str;

// Use a shorter 8-character ID
PrefixedIds::generateUniqueIdUsing(function () {
    return substr(md5(uniqid(mt_rand(), true)), 0, 8);
});

$user = User::create(['name' => 'Jane']);
echo $user->prefixed_id; // Output: user_a1b2c3d4

// Use Laravel's Str helper for a different format
PrefixedIds::generateUniqueIdUsing(function () {
    return Str::random(12);
});

$order = Order::create(['total' => 50.00]);
echo $order->prefixed_id; // Output: order_Xk9mP2nQ4rT1

// Use ULID for sortable IDs
PrefixedIds::generateUniqueIdUsing(function () {
    return strtolower((string) Str::ulid());
});

$product = Product::create(['name' => 'Gadget']);
echo $product->prefixed_id; // Output: prod_01aryz6s41tsp2m3xqjvwy

// Reset to default UUID generation
PrefixedIds::generateUniqueIdUsing(null);

```

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

### Find models by prefixed ID

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Use the PrefixedIds facade to retrieve model instances based on a prefixed identifier string. Supports both standard find methods and findOrFail for exception handling.

```php
$yourModel = Spatie\PrefixedIds\PrefixedIds::find('your_model_fekjlmsme39dmMS');
$otherModel = Spatie\PrefixedIds\PrefixedIds::find('other_model_3Fjmmfsmls');
$otherModel = Spatie\PrefixedIds\PrefixedIds::findOrFail('other_model_3Fjmmfsmls');
```

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

### Finding Laravel Models by Prefixed ID

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Provides methods to retrieve Eloquent models using their unique prefixed IDs. `findByPrefixedId` returns the model or null if not found, while `findByPrefixedIdOrFail` throws an exception if the model is not found.

```php
// On a specific model class
YourModel::findByPrefixedId('your_model_fekjlmsme39dmMS'); // returns YourModel instance or null
YourModel::findByPrefixedIdOrFail('your_model_fekjlmsme39dmMS'); // returns YourModel instance or throws NoPrefixedModelFound

// Automatically determine the model class for a given prefixed id
use Spatie\PrefixedIds\PrefixedIds;
$model = PrefixedIds::getModelClass('user_fj39fj3lsmxlsl'); // returns the correct model instance or null
```

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

### Enable Prefixed IDs with HasPrefixedId Trait

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

Applies the `HasPrefixedId` trait to Eloquent models to automatically generate prefixed IDs upon record creation. This trait handles the ID generation logic.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\PrefixedIds\Models\Concerns\HasPrefixedId;

class User extends Model
{
    use HasPrefixedId;
}

class Order extends Model
{
    use HasPrefixedId;
}

class Product extends Model
{
    use HasPrefixedId;
}
```

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

### Find Models by Prefixed ID using PrefixedIds::find()

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

The `PrefixedIds::find()` method allows you to retrieve any registered model by its prefixed ID. It automatically detects the correct model class based on the ID's prefix. Returns `null` if the model is not found or the prefix is unknown. This is useful for handling generic resource IDs from webhooks or APIs.

```php
<?php

use Spatie\PrefixedIds\PrefixedIds;

// Find models of different types using a single method
$user = PrefixedIds::find('user_550e8400e29b41d4a716446655440000');
$order = PrefixedIds::find('order_6ba7b8109dad11d180b400c04fd430c8');
$product = PrefixedIds::find('prod_f47ac10b58cc4372a5670e02b2c3d479');

// Each variable is an instance of its respective model class
echo get_class($user);    // Output: App\Models\User
echo get_class($order);   // Output: App\Models\Order
echo get_class($product); // Output: App\Models\Product

// Returns null for unknown prefixes or non-existing IDs
$unknown = PrefixedIds::find('unknown_prefix_abc123');
var_dump($unknown); // Output: NULL

// Useful for webhook handlers or API endpoints that accept any resource ID
function handleWebhook(string $resourceId): void
{
    $model = PrefixedIds::find($resourceId);

    if ($model instanceof User) {
        // Handle user-related webhook
    } elseif ($model instanceof Order) {
        // Handle order-related webhook
    }
}
```

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

### Creating a Prefixed ID Column in Laravel Migrations

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Defines a migration to add a `prefixed_id` column to a database table for Eloquent models. This column should be a string, nullable, and unique to store the generated prefixed IDs.

```php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('your_models_table', function (Blueprint $table) {
    $table->string('prefixed_id')->nullable()->unique();
});
```

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

### Registering Models with Prefixed IDs in Laravel

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Registers Eloquent models with their corresponding prefixes for the PrefixedIds package. This is typically done in a service provider. It maps a prefix string to a model class, enabling the package to generate and resolve prefixed IDs correctly.

```php
use Spatie\PrefixedIds\PrefixedIds;

// In a service provider's boot method:
PrefixedIds::registerModels([
    'your_prefix_' => \App\Models\YourModel::class,
    'another_prefix' => \App\Models\AnotherModel::class,
]);
```

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

### Configure route model binding

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Enable prefixed ID support in routes by implementing the getRouteKeyName method in your Eloquent model to return the attribute containing the prefixed ID.

```php
public function getRouteKeyName()
{
    return 'prefixed_id';
}

Route::get('/api/your-models/{yourModel}', YourModelController::class);
```

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

### Customize unique ID generation

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Override the default UUID generation logic by providing a custom closure to the generateUniqueIdUsing method.

```php
Spatie\PrefixedIds\PrefixedIds::generateUniqueIdUsing(function(){
    $length = 8;
    return substr(md5(uniqid(mt_rand(), true)), 0, $length);
});
```

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

### Database Migration for Prefixed ID Column

Source: https://context7.com/spatie/laravel-prefixed-ids/llms.txt

Adds a `prefixed_id` column to your Eloquent model's database table. This column will store the generated prefixed identifiers. It is configured as a unique string.

```php
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class AddPrefixedIdToUsersTable extends Migration
{
    public function up()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->string('prefixed_id')->nullable()->unique();
        });
    }

    public function down()
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('prefixed_id');
        });
    }
}
```

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

### Using HasPrefixedId Trait in Laravel Models

Source: https://github.com/spatie/laravel-prefixed-ids/blob/main/README.md

Applies the HasPrefixedId trait to an Eloquent model to enable the generation and management of prefixed IDs. This trait handles the automatic creation of unique prefixed IDs when a model is saved.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\PrefixedIds\Models\Concerns\HasPrefixedId;

class YourModel extends Model
{
    use HasPrefixedId;
}
```
Tokens:
Raw