mcandylab/laravel-cuid2

CUID2 support for Laravel

v1.2.0 2026-07-12 19:34 UTC

Requires

• php: ^8.2
• illuminate/support: ^12.0 || ^13.0
• visus/cuid2: ^6.0

Requires (Dev)

• orchestra/testbench: ^10.0 || ^11.0
• phpunit/phpunit: ^11.0 || ^12.0

MIT

• Andrey Abramov

• mcandylab
• laravel-cuid2

Published on Packagist.org on 2026-07-12 19:35 UTC

README

🇬🇧 English | 🇷🇺 Русский

Use CUID2 as primary keys for your Eloquent models in Laravel. The package provides a model trait, a global cuid2() helper and schema macros for migrations. Generation is delegated to the visus/cuid2 library.

Requirements

• PHP >= 8.2
• Laravel 12 or 13 (Laravel 13 requires PHP 8.3+)

Installation

composer require mcandylab/laravel-cuid2

The package uses auto-discovery. Publish the config if needed:

php artisan vendor:publish --provider="Mcandylab\LaravelCuid2\LaravelCuid2ServiceProvider" --tag="config"

Usage

Model trait

Add the HasCuid2 trait — the primary key will be automatically populated with a valid CUID2 when a record is created:

use Illuminate\Database\Eloquent\Model;
use Mcandylab\LaravelCuid2\Concerns\HasCuid2;

class Post extends Model
{
    use HasCuid2;
}

The trait sets keyType = 'string' and incrementing = false for you. To generate a cuid2 for more than just the primary key, override uniqueIds():

public function uniqueIds(): array
{
    return [$this->getKeyName(), 'public_id'];
}

Migrations

The cuid2() and foreignCuid2() macros declare char columns of the configured length:

Schema::create('posts', function (Blueprint $table) {
    $table->cuid2()->primary();      // id column
    $table->string('title');
    $table->timestamps();
});

Schema::create('comments', function (Blueprint $table) {
    $table->cuid2()->primary();
    $table->foreignCuid2('post_id')->constrained();
    $table->text('body');
});

For polymorphic relations use cuid2Morphs() (and nullableCuid2Morphs()), the CUID2 counterparts of Laravel's ulidMorphs(). They add a {name}_type string column, a {name}_id char column and a composite index:

Schema::create('tokens', function (Blueprint $table) {
    $table->cuid2()->primary();
    $table->cuid2Morphs('tokenable');          // tokenable_type + tokenable_id
    $table->string('token');
});

// nullable variant
$table->nullableCuid2Morphs('tokenable');

Helper

$id = cuid2();      // 24 characters (or config('laravel-cuid2.length'))
$short = cuid2(10); // arbitrary length 4..32

Facade

use Mcandylab\LaravelCuid2\LaravelCuid2Facade as Cuid2;

Cuid2::generate();          // generate an id
Cuid2::isValid($someId);    // validate a string

Validation

The cuid2 rule validates that a value is a well-formed CUID2. It is available in three forms:

use Illuminate\Validation\Rule;
use Mcandylab\LaravelCuid2\Rules\Cuid2;

$request->validate([
    'id'    => 'cuid2',                  // any valid CUID2
    'token' => 'cuid2:10',              // exact length (4..32)
    'ref'   => [new Cuid2(10)],         // rule object
    'ext'   => [Rule::cuid2(length: 10)], // rule macro
]);

Configuration

config/laravel-cuid2.php:

return [
    // Identifier length (4..32). The cuid2 standard is 24.
    'length' => (int) env('CUID2_LENGTH', 24),
];

Testing

composer test

Changelog

See CHANGELOG.

Contributing

See CONTRIBUTING.

Security

If you discover any security related issues, please open an issue.

Credits

• Andrey Abramov
• All Contributors
• visus-io/php-cuid2

License

The MIT License (MIT). See License File.