Skip to content

Latest commit

 

History

History
400 lines (294 loc) · 12.2 KB

README.md

File metadata and controls

400 lines (294 loc) · 12.2 KB
Raw

UID

build Codacy Badge Packagist Downloads License: MIT Packagist Version Packagist PHP Version Support GitHub code size in bytes

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

  • UUID
  • ULID
  • Snowflake ID
  • Sonyflake ID
  • TBSL
  • NanoId
  • Cuid2

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

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)
Snowflake 0.13951 (godruoyi/php-snowflake: 0.14856)
Sonyflake 0.13821 (godruoyi/php-snowflake: 0.14583)
TBSL 0.0034
NanoID 0.00057
Cuid2 0.01817

Support

Having trouble? Create an issue!

References