tiny-blocks/ksuid

K-Sortable Unique Identifier.

2.0.1 2026-06-27 13:08 UTC

Requires

• php: ^8.5
• tiny-blocks/encoder: ^4.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.52
• infection/infection: ^0.33
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^13.1
• squizlabs/php_codesniffer: ^4.0

MIT

• Gustavo Freze de Araujo Santos

• tiny-blocks
• ksuid
• unique-identifier
• k-sortable

README

• Overview
• Installation
• How to use
• License
• Contributing

Overview

Ksuid stands for K-Sortable Unique Identifier. It's a way to generate globally unique IDs which are partially chronologically sortable.

Installation

composer require tiny-blocks/ksuid

How to use

The library exposes a concrete implementation through the Ksuid class.

Creating a Ksuid

With the random method, a new instance of type Ksuid is created from a timestamp (current unix timestamp - EPOCH) and a payload (cryptographically secure pseudo-random bytes).

<?php

declare(strict_types=1);

use TinyBlocks\Ksuid\Ksuid;

$ksuid = Ksuid::random();

$ksuid->value();     # 2QzPUGEaAKHhVcQYrqQodbiZat1
$ksuid->payload();   # 464932c1194da98e752145d72b8f0aab
$ksuid->unixTime();  # 1686353450
$ksuid->timestamp(); # 286353450

You can also choose from other factory models.

Ksuid::from(payload: hex2bin('9850EEEC191BF4FF26F99315CE43B0C8'), timestamp: 286235327);

Ksuid::fromPayload(value: '0o5Fs0EELR0fUjHjbCnEtdUwQe3');

Ksuid::fromTimestamp(value: 286235327);

Inspecting a Ksuid

You can inspect the components used to create a Ksuid, using the inspectFrom method.

$ksuid = Ksuid::inspectFrom(ksuid: '2QzPUGEaAKHhVcQYrqQodbiZat1');

This will output the following array:

[
    'time'      => '2023-06-09 20:30:50 -0300 -03',
    'payload'   => '464932c1194da98e752145d72b8f0aab',
    'timestamp' => 286353450
]

License

Ksuid is licensed under MIT.

Contributing

Please follow the contributing guidelines to contribute to the project.