README

Human Keys offers an alternative to using UUIDs for your Laravel Models. By default, it generates ksuids, similar to what Stripe uses for their resources. Ksuids are human-readable and sortable.

Example:

• pos_2JvL8Gv5mirjbIVAlSRFrC8EaWR for Models/Post.php
• usr_p6UEyCc8D8ecLijAI5zVwOTP3D0 for Models/User.php

Installation

You can install the package via composer:

composer require rawilk/human-keys

You can publish the config file with:

php artisan vendor:publish --tag="human-keys-config"

If you are using the KsuidGenerator (which is the default), you will need to install the tuupola/ksuid package:

composer require tuupola/ksuid

See Using a Different Generator for more information.

You can view the default configuration here: https://github.com/rawilk/human-keys/blob/main/config/human-keys.php

Usage

To get started, use the HasHumanKey trait on your model:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Rawilk\HumanKeys\Concerns\HasHumanKey;

class Post extends Model
{
    use HasHumanKey;
}

Using a Different Generator

By default, the package is configured to use the KsuidGenerator, however you may define a custom generator to use under the generator key in the config file.

Below you will find out how to use the different generators that are included with this package, and how to create your own.

KsuidGenerator

This is the default generator that is used. You will need to install the tuupola/ksuid package to use it. This generator will generate something like this: pos_2JvL8Gv5mirjbIVAlSRFrC8EaWR.

composer require tuupola/ksuid

SnowflakeGenerator

This generator generates IDs based on the Snowflake Algorithm announced by Twitter. You will need to install the godruoyi/php-snowflake package to use it. This generator will generate something like this: pos_451734027389370636.

composer require godruoyi/php-snowflake

UuidGenerator

As of v1.1.0, you can use the UuidGenerator, which generates ids using Laravel's Str::uuid() helper. Ids generated with this generator will look like: pos_b8a34e34553a41b885ae218ae81abd42. The only requirement for this generator is to register it in the config file; there are no external dependencies that are required for it.

// config/human-keys.php

'generator' => \Rawilk\HumanKeys\Generators\UuidGenerator::class,

Custom Generator

You may define your own generator by implementing the Rawilk\HumanKeys\Contracts\KeyGenerator contract. From the generator, you may return an ID based on your application's requirements.

namespace App\Generators;

use Rawilk\HumanKeys\Contracts\KeyGenerator;

class CustomGenerator implements KeyGenerator
{
    public function generate(?string $prefix = null): string
    {
        // Generate your ID here...
    }
}

Then, in the config file, you may specify your generator:

'generator' => App\Generators\CustomGenerator::class,

Overriding the Key Prefix

By default, the key the first 3 characters of the model's class name. You may override this by defining a humanKeyPrefix method on your model:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Rawilk\HumanKeys\Concerns\HasHumanKey;

class Post extends Model
{
    use HasHumanKey;

    public static function humanKeyPrefix() : string
    {
        // You should omit an underscore at the end of the prefix, as it will be added automatically
        // by the generator.
        return 'custom_prefix';
    }
}

Using it For Other Columns

By default, the HasHumanKey trait will generate an ID for your model's primary key column. This may not be what you want, however. In your model, you may override the humanKeys method and return a listing of the columns that should be generated for.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Rawilk\HumanKeys\Concerns\HasHumanKey;

class Post extends Model
{
    use HasHumanKey;

    public function humanKeys(): array
    {
        return ['human_key'];
    }
}

Now the human_key column will be generated for instead of the primary key. This is useful if your model is already using auto-incrementing IDs or if you are using UUID or ULID for your primary keys. The HasHumanKey trait is fully compatible with Laravel's HasUuids or HasUlids traits.

If you really need to, you may even override the newHumanKey method on your model to generate a custom ID in a way of your choosing, however in most cases this shouldn't be necessary.

Scripts

Setup

For convenience, you can run the setup bin script for easy installation for local development.

./bin/setup.sh

Formatting

Although formatting is done automatically via workflow, you can format php code locally before committing with a composer script:

composer format

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security

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

Alternatives

This package is very similar to the laravel-human-keys package by oneduo, however I created my own version because I wanted more flexibility in which columns IDs are generated for.

Other alternatives include:

• spatie/laravel-prefixed-ids

Credits

• Randall Wilk
• All Contributors
• godruoyi/php-snowflake
• tuupola/ksuid

License

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