README

An AIO Unique ID generator written in PHP. Supports (references available at the bottom),

UUID
ULID
Snowflake ID
Sonyflake ID
TBSL
NanoId
Cuid2

Prerequisites
Installation
Usage
- UUID
  - UUID v1
  - UUID v3
  - UUID v4
  - UUID v5
  - UUID v6
  - UUID v7
  - UUID v8
  - GUID
  - Additional
- ULID
- Snowflake ID
- Sonyflake ID
- TBSL ID
- RandomId
  - NanoId
  - Cuid2
Benchmark
Support
References

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();

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();

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 as well.

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();

Get v8 UUID using predefined node:

\Infocyph\UID\UUID::v8($node); // check additional section for, how to generate one

GUID

GUID generator, works in all platform. Generate:

\Infocyph\UID\UUID::guid()

Note: Sending false in only parameter will return the string enclosed with Braces

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

// 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):

// 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);

RandomId

With this you can generate RandomIds. These are great for usage where you don't want a large length/formatted IDs like UUID4. These IDs are unique & can't be backtracked.

NanoID (URL friendly Unique Random ID)

Generate

// By default, it will generate id of length 21.
// You can pass in desired length
\Infocyph\UID\RandomId::nanoId();

Cuid2 (URL friendly, secure & collision free)

Generate

// By default, it will generate id of length 24.
// You can pass in desired length in between 4 & 24
\Infocyph\UID\RandomId::cuid2();

Benchmark

Support

Having trouble? Create an issue!

References

UUID (RFC4122): https://tools.ietf.org/html/rfc4122
UUID (Drafts/Proposals): https://datatracker.ietf.org/doc/draft-ietf-uuidrev-rfc4122bis
ULID: https://github.com/ulid/spec
Snowflake ID: https://github.com/twitter-archive/snowflake/tree/snowflake-2010
Sonyflake ID: https://github.com/sony/sonyflake
TBSL ID: https://github.com/infocyph/UID/blob/main/TBSL.md
NanoID: https://github.com/ai/nanoid
Cuid2: https://github.com/paralleldrive/cuid2

infocyph / uid

Maintainers

Details