Skip to content
/ UID Public

UUID (RFC 4122 + Unofficial/Draft), ULID, Snowflake ID, Sonyflake ID, NanoId, Cuid2, TBSL (library exclusive) generator!

License

Notifications You must be signed in to change notification settings

infocyph/UID

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

32 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

UID

build Codacy Badge Libraries.io dependency status for GitHub repo Packagist Downloads License: MIT Packagist Version Packagist PHP Version Support GitHub code size in bytes

An AIO Unique ID generator for php. Supports,

  • UUID (RFC 4122 + Unofficial/Draft)
  • ULID (ulid specification)
  • Snowflake ID (Twitter Snowflake specification)
  • Sonyflake ID (Snowflake Inspired specification, ported from Golang)
  • TBSL (library exclusive)

Table of contents

Prerequisites

Language: PHP 8/+

Installation

composer require infocyph/uid

Usage

UUID (Universal Unique Identifier)

The node specific UUID's $node parameter (1, 6, 7, 8) is optional. If not provided, it will be generated randomly. But, if you wanna track the source of the UUIDs, you should use it (pre-define the node per server & pass it accordingly).

UUID v1: Time-based UUID.

  • Generate v1 UUID
// Get v1 UUID
\Infocyph\UID\UUID::v1();
// alternatively can also use
\Infocyph\UID\uuid1();
  • Pass your pre-generated node (for node specific UUID)
\Infocyph\UID\UUID::v1($node); // check additional section for how to generate one

UUID v3: Namespace based UUID.

  • Generate v3 UUID
// Get v3 UUID
\Infocyph\UID\UUID::v3('a pre-generated UUID', 'the string you wanna get UUID for');
// alternatively can also use
\Infocyph\UID\uuid3();
  • Get v3 UUID for predefined namespaces (RFC4122 #Appendix C)
/**
* You can pass X500, URL, OID, DNS (check RFC4122 #Appendix C)
*/
\Infocyph\UID\UUID::v3('url', 'abmmhasan.github.io');
  • You can generate a UUID & use as namespace as well
\Infocyph\UID\UUID::v3('fa1700dd-828c-4d1b-8e6d-a6104807da90', 'abmmhasan.github.io');

UUID v4: Random UUID.

  • Generate v4 UUID
// Get v4 UUID (completely random)
\Infocyph\UID\UUID::v4();
// alternatively can also use
\Infocyph\UID\uuid4();

UUID v5: Namespace based UUID.

  • Generate v5 UUID
// Get v5 UUID
\Infocyph\UID\UUID::v5('a pre-generated UUID', 'the string you wanna get UUID for');
// alternatively can also use
\Infocyph\UID\uuid5();
  • Get v5 UUID for predefined namespaces (RFC4122 #Appendix C)
/**
* You can pass X500, URL, OID, DNS (check RFC4122 #Appendix C)
*/
\Infocyph\UID\UUID::v5('url', 'abmmhasan.github.io');
  • You can generate a UUID & use as namespace as well
\Infocyph\UID\UUID::v5('fa1700dd-828c-4d1b-8e6d-a6104807da90', 'abmmhasan.github.io');

UUID v6 (draft-based/unofficial): Time-based UUID.

  • Generate v6 UUID
// Get v6 UUID (Time based)
\Infocyph\UID\UUID::v6();
// alternatively can also use
\Infocyph\UID\uuid6();
  • Or if you wanna get v6 UUID using predefined node:
\Infocyph\UID\UUID::v6($node); // check additional section for how to generate one

UUID v7 (draft-based/unofficial): Time-based UUID.

  • Generate v7 UUID
// Get v7 UUID for current time
\Infocyph\UID\UUID::v7();
// alternatively can also use
\Infocyph\UID\uuid7();
  • Or if you wanna get v7 UUID using predefined node:
\Infocyph\UID\UUID::v7(null, $node); // check additional section for, how to generate one
  • Or if you wanna get v7 UUID using predefined time:
$timeInterface = new DateTime(); // DateTime implements DateTimeInterface
\Infocyph\UID\UUID::v7($timeInterface);
  • You can combine both parameters together.

UUID v8 (draft-based/unofficial): Time-based UUID. Lexicographically sortable.

  • Generate v8 UUID
// Get v8 UUID
\Infocyph\UID\UUID::v8();
// alternatively can also use
\Infocyph\UID\uuid8();
  • Or if you wanna get v8 UUID using predefined node:
\Infocyph\UID\UUID::v8($node); // check additional section for, how to generate one

Additional

  • Generate node for further use (with version: 1, 6, 7, 8)
\Infocyph\UID\UUID::getNode();
  • Parse any UUID string:
\Infocyph\UID\UUID::parse($uuid); // returns ['isValid', 'version', 'time', 'node']

ULID (Universally Unique Lexicographically Sortable Identifier)

  • Generating ULID is very simple,
\Infocyph\UID\ULID::generate();
  • Or if you wanna get ULID for specific time:
\Infocyph\UID\ULID::generate(new DateTimeImmutable('2020-01-01 00:00:00'));
  • Extract datetime from any ULID string:
\Infocyph\UID\ULID::getTime($ulid); // returns DateTimeInterface object
  • Validate any ULID string:
\Infocyph\UID\ULID::isValid($ulid); // true/false

Snowflake ID

  • Generate a new Snowflake ID (You can also pass your pre-generated worker_id & datacenter_id for server/module detection):
// Get Snowflake ID
// optionally you can set worker_id & datacenter_id, for server/module detection
\Infocyph\UID\Snowflake::generate();
// alternatively
\Infocyph\UID\snowflake();
  • Parse Snowflake ID (get the timestamp, sequence, worker_id, datacenter_id from any Snowflake ID):
// Parse Snowflake ID
// returns [time => DateTimeInterface object, sequence, worker_id, datacenter_id]
\Infocyph\UID\Snowflake::parse($snowflake);
  • Specify start time for Snowflake ID (a Snowflake ID is unique upto 69 years from the start date):
// By default, the start time is set to `2020-01-01 00:00:00`, which is changeable
// but if changed, this should always stay same as long as your project lives
// & must call this before any Snowflake call (generate/parse)
\Infocyph\UID\Snowflake::setStartTimeStamp('2000-01-01 00:00:00');

Sonyflake ID

  • Generate a new Sonyflake ID (You can also pass your pre-generated machine_id for server detection):
// Get Sonyflake ID
// optionally set machine_id, for server detection
\Infocyph\UID\Sonyflake::generate();
// alternatively
\Infocyph\UID\sonyflake();
  • Parse Sonyflake ID (get the timestamp, sequence, machine_id from any Snowflake ID):
// Parse Sonyflake ID
// returns [time => DateTimeInterface object, sequence, machine_id]
\Infocyph\UID\Sonyflake::parse($sonyflake);
  • Specify start time for Sonyflake ID (a Sonyflake ID is unique upto 174 years from the start date):
// By default, the start time is set to `2020-01-01 00:00:00`, which is changeable
// but if changed, this should always stay same as long as your project lives
// & must call this before any Sonyflake call (generate/parse)
\Infocyph\UID\Sonyflake::setStartTimeStamp('2000-01-01 00:00:00');

TBSL: Time-Based Keys with Lexicographic Sorting (library exclusive)

  • Get TBSL ID (You can also pass your pre-generated machine_id for server detection):
// Get TBSL ID
// optionally set machine_id, for server detection
\Infocyph\UID\TBSL::generate();
// alternatively
\Infocyph\UID\tbsl();
  • Parse TBSL ID (get the timestamp, machine_id):
// Parse TBSL
// returns [isValid, time => DateTimeInterface object, machine_id]
\Infocyph\UID\TBSL::parse($tbsl);

Benchmark

Type Generation time (ms)
UUID v1 (random node) 0.00411 (ramsey/Uuid: 0.18753)
UUID v1 (fixed node) 0.00115 (ramsey/Uuid: 0.17386)
UUID v3 (custom namespace) 0.00257 (ramsey/Uuid: 0.03015)
UUID v4 0.00362 (ramsey/Uuid: 0.16501)
UUID v5 (custom namespace) 0.00108 (ramsey/Uuid: 0.03658)
UUID v6 (random node) 0.00444 (ramsey/Uuid: 0.17469)
UUID v6 (fixed node) 0.00164 (ramsey/Uuid: 0.17382)
UUID v7 (random node) 0.00503 (ramsey/Uuid: 0.16278)
UUID v7 (fixed node)** 0.00154 (ramsey/Uuid: 0.18753)
UUID v8 (random node) 0.00505 (ramsey/Uuid: N/A)
UUID v8 (fixed node) 0.00209 (ramsey/Uuid: 0.16029 *predefined random node, not usable as signature)
ULID 0.00506 (robinvdvleuten/php-ulid: 0.00508)
TBSL 0.0034 (library unique)
Snowflake 0.13951 (godruoyi/php-snowflake: 0.14856)
Sonyflake 0.13821 (godruoyi/php-snowflake: 0.14583)

Support

Having trouble? Create an issue!

References

About

UUID (RFC 4122 + Unofficial/Draft), ULID, Snowflake ID, Sonyflake ID, NanoId, Cuid2, TBSL (library exclusive) generator!

Topics

Resources

License

Security policy

Stars

Watchers

Forks

Languages