README

Prefixing an id will help users to recognize what kind of id it is. Stripe does this by default: customer ids are prefixed with cus, secret keys in production are prefixed with sk_live_, secret keys of a testing environment with sk_test_ and so on....

This package can generate such friendly prefixed ids for Eloquent models. Here's how such generated ids could look like.

user_fj39fj3lsmxlsl
test_token_dvklms109dls

The package can retrieve the model for a given prefixed id.

// on a specific model
User::findByPrefixedId('user_fj39fj3lsmxlsl'); // returns a User model or `null`
User::findByPrefixedIdOrFail('user_fj39fj3lsmxlsl'); // returns a User model or throws `NoPrefixedModelFound`

// automatically determine the model of a given prefixed id
$user = PrefixedIds::getModelClass('user_fj39fj3lsmxlsl') // returns the right model for the id or `null`;

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require spatie/laravel-prefixed-ids

Preparing your models

On each model that needs a prefixed id, you should use the Spatie\PrefixedIds\Models\Concerns\HasPrefixedId trait.

namespace App\Models;

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

class YourModel extends Model
{
    use HasPrefixedId;
}

Preparing the database

For each model that needs a prefixed id, you'll need to write a migration to add a prefixed_id column to its underlying table.

If you wish to use another attribute name, you should publish the config file (see below) and set the prefixed_id_attribute_name config value to the attribute name of your liking.

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

Registering models with prefixed ids

To register your models, you should pass the desired prefix and the class name of your model to PrefixedIds::registerModels.

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

Typically, you would put the code above in a service provider.

Publish the config file

Optionally, You can publish the config file with:

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

This is the contents of the published config file:

return [
    /*
     * The attribute name used to store prefixed ids on a model
     */
    'prefixed_id_attribute_name' => 'prefixed_id',
];

Usage

When a model is created, it will automatically have a unique, prefixed id in the prefixed_id attribute.

$model = YourModel::create();
$model->prefixed_id // returns a random id like `your_model_fekjlmsme39dmMS`

Finding a specific model

You can find the model with a given prefix by calling findByPrefixedId on it.

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

Finding across models

You can call find on Spatie\PrefixedIds\PrefixedIds to automatically get the right model for any given prefixed id.

$yourModel = Spatie\PrefixedIds\PrefixedIds::find('your_model_fekjlmsme39dmMS'); // returns an instance of `YourModel` or `null`
$otherModel = Spatie\PrefixedIds\PrefixedIds::find('other_model_3Fjmmfsmls'); // returns an instance of `OtherModel` or `null`
$otherModel = Spatie\PrefixedIds\PrefixedIds::findOrFail('other_model_3Fjmmfsmls'); // returns an instance of `OtherModel` or throws `NoPrefixedModelFound`

Customizing the unique ID generated

You can use the function Spatie\PrefixedIds\PrefixedIds::generateUniqueIdUsing() to pass in a function to generate the unique ID. By default the library will use Str::uuid() to generate the ID.

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

Using the prefixed ids in your routes

To use the prefixed ids in your routes, you'll have to add the getRouteKeyName method to your model. It should return the name of the attribute that holds the prefixed id.

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

With this in place a route defined as...

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

... can be invoked with an URL like /api/your-models/your_model_fekjlmsme39dmMS.

You'll find more info on route model binding in the Laravel docs.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

This package is inspired by excid3/prefixed_ids

License

The MIT License (MIT). Please see License File for more information.

spatie / laravel-prefixed-ids

Maintainers

Details