Spatie Laravel Prefixed IDs

To customize the attribute name used to store prefixed IDs, publish the configuration file using the following Artisan command:

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

You must register your models and their corresponding prefixes with the PrefixedIds::registerModels method. This is typically done within a Service Provider. The keys in the array are the prefixes (including the trailing underscore) and the values are the model class names.

Spatie\PrefixedIds\PrefixedIds::registerModels([
    'your_prefix_' => YourModel::class,
    'another_prefix' => AnotherModel::class,
]);

Each model using prefixed IDs requires a prefixed_id column in its database table. This column should be a string, nullable, and unique.

If you want to use an attribute name other than prefixed_id, you must publish the config file and update the prefixed_id_attribute_name value.

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

To enable prefixed IDs on an Eloquent model, use the Spatie\PrefixedIds\Models\Concerns\HasPrefixedId trait within your model class.

namespace App\Models;

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

class YourModel extends Model
{
    use HasPrefixedId;
}

Install the package using the standard Composer command:

composer require spatie/laravel-prefixed-ids

To allow Laravel to use the prefixed_id attribute for route model binding, override the getRouteKeyName method in your model to return the name of the attribute holding the prefixed ID.

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

// Example route usage:
// Route::get('/api/your-models/{yourModel}', YourModelController::class)
// URL: /api/your-models/your_model_fekjlmsme39dmMS

By default, the package uses Str::uuid() to generate the unique part of the ID. You can override this behavior by passing a custom callback to Spatie\PrefixedIds\PrefixedIds::generateUniqueIdUsing().

// generate a unique Id with a set length
Spatie\PrefixedIds\PrefixedIds::generateUniqueIdUsing(function(){
    $length = 8;
    return substr(md5(uniqid(mt_rand(), true)), 0, $length);
});

Once a model is using the HasPrefixedId trait, you can retrieve it using its prefixed ID via the following methods on the model class:

• findByPrefixedId($id): Returns the model instance or null if not found.
• findByPrefixedIdOrFail($id): Returns the model instance or throws a NoPrefixedModelFound exception.

YourModel::findByPrefixedId('your_model_fekjlmsme39dmMS'); // returns an instance of YourModel
YourModel::findByPrefixedId('non-existing-id'); // returns null
YourModel::findByPrefixedIdOrFail('non-existing-id'); // throws NoPrefixedModelFound

Once models are registered, you can use PrefixedIds::find() to resolve a model instance from a string containing a prefix and an ID. If no model matches the prefix, it returns null.

use Spatie\PrefixedIds\PrefixedIds;

$model = PrefixedIds::find('usr_12345');

if ($model) {
    // Found the model
}

To enable the package to resolve models from prefixed IDs, you must register your models with their corresponding prefixes using the PrefixedIds class. You can register multiple models at once using registerModels() or a single model using registerModel().

use Spatie\PrefixedIds\PrefixedIds;
use App\Models\User;
use App\Models\Post;

// Register multiple models
PrefixedIds::registerModels([
    'usr_' => User::class,
    'pst_' => Post::class,
]);

// Or register a single model
PrefixedIds::registerModel('usr_', User::class);

If you need to reset the state of the package (for example, in a testing environment), you can use clearRegisteredModels() to remove all currently registered prefixes and model mappings.

use Spatie\PrefixedIds\PrefixedIds;

PrefixedIds::clearRegisteredModels();