PHPackages                             rawilk/human-keys - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. rawilk/human-keys

ActiveLibrary[Utility & Helpers](/categories/utility)

rawilk/human-keys
=================

Use Stripe-like IDs for your models.

v2.0.0(1mo ago)73.2k↑103.6%[1 PRs](https://github.com/rawilk/human-keys/pulls)MITPHPPHP ^8.2CI passing

Since May 8Pushed 1w ago1 watchersCompare

[ Source](https://github.com/rawilk/human-keys)[ Packagist](https://packagist.org/packages/rawilk/human-keys)[ Docs](https://github.com/rawilk/human-keys)[ GitHub Sponsors](https://github.com/rawilk)[ RSS](/packages/rawilk-human-keys/feed)WikiDiscussions main Synced yesterday

READMEChangelog (6)Dependencies (19)Versions (13)Used By (0)

human-keys
==========

[](#human-keys)

[![Latest Version on Packagist](https://camo.githubusercontent.com/f0bd30c117397ec4732abcbe82d3ecc9a862e0b892cf3ee14220d2db535c39c6/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f726177696c6b2f68756d616e2d6b6579732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rawilk/human-keys)[![Tests](https://github.com/rawilk/human-keys/workflows/Tests/badge.svg?style=flat-square)](https://github.com/rawilk/human-keys/workflows/Tests/badge.svg?style=flat-square)[![Total Downloads](https://camo.githubusercontent.com/827bb7c5e7d4dd64d4e4733cee8bf9ba8f8c641bcc2cd5cc6e8a58b34b160010/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f726177696c6b2f68756d616e2d6b6579732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rawilk/human-keys)[![PHP from Packagist](https://camo.githubusercontent.com/7e0dafc6382cff37a31ea0a22c93dd29115cbd258c08d02064da087ae42bd218/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f726177696c6b2f68756d616e2d6b6579733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/rawilk/human-keys)[![License](https://camo.githubusercontent.com/f6d9d393e8d030cc6db05e00569351671536f258e3cd7d689ef816cadfb90402/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f726177696c6b2f68756d616e2d6b6579733f7374796c653d666c61742d737175617265)](https://github.com/rawilk/human-keys/blob/main/LICENSE.md)

[![social image](https://camo.githubusercontent.com/b9db60486e5430515fbf931577863467a09f7d8bb0beac5cc9efff596175a5b9/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f48756d616e2532304b6579732e706e673f7468656d653d6c69676874267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d726177696c6b25324668756d616e2d6b657973267061747465726e3d617263686974656374267374796c653d7374796c655f31266465736372697074696f6e3d5573652b5374726970652d6c696b652b6b6579732b666f722b796f75722b6d6f64656c732e266d643d312673686f7757617465726d61726b3d3026666f6e7453697a653d313030707826696d616765733d6b6579)](https://camo.githubusercontent.com/b9db60486e5430515fbf931577863467a09f7d8bb0beac5cc9efff596175a5b9/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f48756d616e2532304b6579732e706e673f7468656d653d6c69676874267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d726177696c6b25324668756d616e2d6b657973267061747465726e3d617263686974656374267374796c653d7374796c655f31266465736372697074696f6e3d5573652b5374726970652d6c696b652b6b6579732b666f722b796f75722b6d6f64656c732e266d643d312673686f7757617465726d61726b3d3026666f6e7453697a653d313030707826696d616765733d6b6579)

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
------------

[](#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](#using-a-different-generator) for more information.

You can view the default configuration here:

Usage
-----

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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
-------

[](#scripts)

### Setup

[](#setup)

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

```
./bin/setup.sh
```

### Formatting

[](#formatting)

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

```
composer format
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

Security
--------

[](#security)

Please review [my security policy](.github/SECURITY.md) on how to report security vulnerabilities.

Alternatives
------------

[](#alternatives)

This package is very similar to the [laravel-human-keys](https://github.com/oneduo/laravel-human-keys) package by [oneduo](https://github.com/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](https://github.com/spatie/laravel-prefixed-ids)

Credits
-------

[](#credits)

- [Randall Wilk](https://github.com/rawilk)
- [All Contributors](../../contributors)
- [godruoyi/php-snowflake](https://github.com/godruoyi/php-snowflake)
- [tuupola/ksuid](https://github.com/tuupola/ksuid)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance94

Actively maintained with recent releases

Popularity27

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity64

Established project with proven stability

 Bus Factor1

Top contributor holds 70.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~184 days

Recently: every ~201 days

Total

7

Last Release

46d ago

Major Versions

v1.1.1 → v2.0.02026-05-18

PHP version history (4 changes)v1.0.0PHP ^8.1|^8.2

v1.1.0PHP ^8.1|^8.2|^8.3

v1.1.1PHP ^8.1

v2.0.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/1e2f599d4d290bbb514a933d4f21c3f18fb093f5f8a9994cb17f5469853c749c?d=identicon)[rawilk](/maintainers/rawilk)

---

Top Contributors

[![rawilk](https://avatars.githubusercontent.com/u/22842525?v=4)](https://github.com/rawilk "rawilk (78 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (22 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (11 commits)")

---

Tags

human-readable-keysksuidsnowflakelaravelstripeuuidulidkeysrawilksnowflakeksuidlaravel-human-keyshuman-keys

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/rawilk-human-keys/health.svg)

```
[![Health](https://phpackages.com/badges/rawilk-human-keys/health.svg)](https://phpackages.com/packages/rawilk-human-keys)
```

###  Alternatives

[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.8M47](/packages/spatie-laravel-pdf)[codewithdennis/filament-select-tree

The multi-level select field enables you to make single selections from a predefined list of options that are organized into multiple levels or depths.

329530.5k29](/packages/codewithdennis-filament-select-tree)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)[worksome/exchange

Check Exchange Rates for any currency in Laravel.

124603.0k](/packages/worksome-exchange)[tarfin-labs/event-machine

Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.

199.4k](/packages/tarfin-labs-event-machine)[tapp/filament-form-builder

User facing form builder using Filament components

132.4k3](/packages/tapp-filament-form-builder)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)