tuupola / ksuid
K-Sortable Globally Unique IDs
Installs: 684 272
Dependents: 3
Suggesters: 1
Security: 0
Stars: 103
Watchers: 6
Forks: 3
Open Issues: 1
Requires
- php: ^7.1|^8.0
- tuupola/base62: ^1.0|^2.0
Requires (Dev)
- overtrue/phplint: ^1.0
- phpstan/phpstan: ^0.12.42
- phpunit/phpunit: ^7.0|^8.0|^9.0
- squizlabs/php_codesniffer: ^3.0
README
This library implements the K-Sortable Globally Unique IDs from Segment. See also the article called A Brief History of the UUID.
KSUID is for K-Sortable Unique IDentifier. It's a way to generate globally unique IDs similar to RFC 4122 UUIDs, but contain a time component so they can be "roughly" sorted by time of creation. The remainder of the KSUID is randomly generated bytes.
Install
Install with composer.
$ composer require tuupola/ksuid
This branch requires PHP 7.1 or up. The older 1.x
branch supports also PHP 5.6 and 7.0.
$ composer require "tuupola/ksuid:^1.0"
Usage
Included Base62 implementation has both PHP and GMP based encoders. By default encoder and decoder will use GMP functions if the extension is installed. If GMP is not available pure PHP encoder will be used instead.
Note! Throughout the code the term timestamp
refers to KSUID timestamp. The term unixtime
refers to the traditional Unix time. KSUID timestamp and Unix time have different Epoch.
use Tuupola\Ksuid; $ksuid = new Ksuid; print $ksuid; /* p6UEyCc8D8ecLijAI5zVwOTP3D0 */ print $ksuid->timestamp(); /* 94985761 */ print $ksuid->unixtime(); /* 1494985761 */ print bin2hex($ksuid->payload()); /* d7b6fe8cd7cff211704d8e7b9421210b */ $datetime = (new \DateTimeImmutable) ->setTimestamp($ksuid->unixtime()) ->setTimeZone(new \DateTimeZone("UTC")); print $datetime->format("Y-m-d H:i:s"); /* 2017-05-17 01:49:21 */
If you prefer static syntax you can use one of the provided factories.
use Tuupola\KsuidFactory as Ksuid; $ksuid = Ksuid::create(); $ksuid = Ksuid::fromString("0o5Fs0EELR0fUjHjbCnEtdUwQe3"); $binary = hex2bin("05a95e21d7b6fe8cd7cff211704d8e7b9421210b"); $ksuid = Ksuid::fromBytes($binary); $ksuid = Ksuid::fromTimestamp(94985761); $ksuid = Ksuid::fromUnixtime(1494985761); $timestamp = 94985761; $payload = hex2bin("d7b6fe8cd7cff211704d8e7b9421210b"); $ksuid = Ksuid::fromTimestampAndPayload($timestamp, $payload);
Testing
You can run tests either manually or automatically on every code change. Automatic tests require entr to work.
$ make test
$ brew install entr $ make watch
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email tuupola@appelsiini.net instead of using the issue tracker.
License
The MIT License (MIT). Please see License File for more information.