spatie/laravel-prefixed-ids
Stars: 150
Forks: 11
Pull Requests: 8
Issues: 2
Watchers: 3
Last Updated: 2023-01-24 23:47:02
Friendly prefixed IDs for Laravel models
License: MIT License
Languages: PHP
Friendly prefixed IDs for Laravel models
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-idsPreparing 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 testChangelog
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.