tiny-blocks/ksuid

K-Sortable Unique Identifier.

1.2.0 2024-10-04 04:18 UTC

Requires

• php: ^8.2
• tiny-blocks/encoder: ^2

Requires (Dev)

• infection/infection: ^0.29
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^1
• phpunit/phpunit: ^11
• squizlabs/php_codesniffer: ^3.10

Suggests

• ext-gmp: Enables faster math with arbitrary-precision integers using GMP.

MIT

• Gustavo Freze de Araujo Santos

• identifier
• psr
• unique
• base62
• tiny-blocks
• ksuid

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

$ksuid = Ksuid::random();

$ksuid->getValue();     # 2QzPUGEaAKHhVcQYrqQodbiZat1
$ksuid->getPayload();   # 464932c1194da98e752145d72b8f0aab
$ksuid->getUnixTime();  # 1686353450
$ksuid->getTimestamp(); # 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'); # 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.