Skip to content

Commit

Permalink
updated doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@abmmhasan
abmmhasan committed May 3, 2024
1 parent 170e887 commit d82cdc4
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 40 deletions.
63 changes: 30 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@ if you wanna track the source of the UUIDs, you should use it (pre-define the no
```php
// Get v1 UUID (Time based)
\Infocyph\UID\UUID::v1();

// alternatively can also use
\Infocyph\UID\uuid1();

Expand All @@ -71,27 +70,25 @@ if you wanna track the source of the UUIDs, you should use it (pre-define the no

```php
// Get v3 UUID for 'TestString'
\Infocyph\UID\UUID::v3('TestString');

\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 an URL & pre-defined namespace
* You can pass X500, URL, OID, DNS (check RFC4122 #Appendix C)
*/
\Infocyph\UID\UUID::v3('abmmhasan.github.io','url');
\Infocyph\UID\UUID::v3('url', 'abmmhasan.github.io');

// You can generate a random UUID & use as namespace as well
\Infocyph\UID\UUID::v3('abmmhasan.github.io','fa1700dd-828c-4d1b-8e6d-a6104807da90');
\Infocyph\UID\UUID::v3('fa1700dd-828c-4d1b-8e6d-a6104807da90', 'abmmhasan.github.io');
```

#### UUID v4: Random UUID.

```php
// Get v4 UUID (completely random)
\Infocyph\UID\UUID::v4();

// alternatively can also use
\Infocyph\UID\uuid4();
```
Expand All @@ -102,19 +99,18 @@ Better replacement for v3 due to better hashing algorithm (SHA1 instead of MD5).

```php
// Get v5 UUID for 'TestString'
\Infocyph\UID\UUID::v5('TestString');

\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 an URL & pre-defined namespace
* You can pass X500, URL, OID, DNS (check RFC4122 #Appendix C)
*/
\Infocyph\UID\UUID::v5('abmmhasan.github.io','url');
\Infocyph\UID\UUID::v5('url', 'abmmhasan.github.io');

// You can generate a random UUID & use as namespace as well
\Infocyph\UID\UUID::v5('abmmhasan.github.io','fa1700dd-828c-4d1b-8e6d-a6104807da90');
\Infocyph\UID\UUID::v5('fa1700dd-828c-4d1b-8e6d-a6104807da90', 'abmmhasan.github.io');
```

#### UUID v6 (draft-based/unofficial): Time-based UUID.
Expand All @@ -124,7 +120,6 @@ Better replacement for v1. Provides more randomness & uniqueness.
```php
// Get v6 UUID (Time based)
\Infocyph\UID\UUID::v6();

// alternatively can also use
\Infocyph\UID\uuid6();

Expand All @@ -135,22 +130,24 @@ Better replacement for v1. Provides more randomness & uniqueness.
#### UUID v7 (draft-based/unofficial): Time-based UUID.

```php
// Get v7 UUID (Time based)
// Get v7 UUID for curren time
\Infocyph\UID\UUID::v7();

// alternatively can also use
\Infocyph\UID\uuid7();

// Pass your pre-generated node (for node specific UUID)
\Infocyph\UID\UUID::v7($node); // check additional section for how to generate one
// Pass your pre-generated node (for node specific UUID) for current time
\Infocyph\UID\UUID::v7(null, $node); // check additional section for how to generate one

// Get v7 UUID for pre-define time using DateTimeInterface
$timeInterface = new DateTime(); // DateTime implements DateTimeInterface
\Infocyph\UID\UUID::v7($timeInterface);
```

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

```php
// Get v6 UUID (Time based)
\Infocyph\UID\UUID::v8();

// alternatively can also use
\Infocyph\UID\uuid8();

Expand Down Expand Up @@ -237,23 +234,23 @@ Library exclusive.

## Benchmark

| Type | Generation time (ms) |
|:---------------------------|:--------------------:|
| UUID v1 (random node) | 0.00124 |
| UUID v1 (fixed node) | 0.00095 |
| UUID v3 (custom namespace) | 0.00076 |
| UUID v4 | 0.00071 |
| UUID v5 (custom namespace) | 0.0009 |
| UUID v6 (random node) | 0.0014 |
| UUID v6 (fixed node) | 0.00142 |
| UUID v7 (random node) | 0.0014 |
| UUID v7 (fixed node) | 0.00149 |
| UUID v8 (random node) | 0.0018 |
| UUID v8 (fixed node) | 0.00178 |
| ULID | 0.0018 |
| TBSL | 0.00081 |

_Note: Snowflake & Sonyflake not included, due to their way of work_
| 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

Expand Down
15 changes: 8 additions & 7 deletions src/UUID.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,12 +65,12 @@ public static function v1(string $node = null): string
/**
* Generates the v3 UUID for a given string using the specified namespace.
*
* @param string $string The string to generate the hash for.
* @param string $namespace The namespace to use for the hash generation.
* @param string $string The string to generate the hash for.
* @return string
* @throws UUIDException
*/
public static function v3(string $string, string $namespace): string
public static function v3(string $namespace, string $string): string
{
$namespace = self::nsResolve($namespace);
if (!$namespace) {
Expand All @@ -95,12 +95,12 @@ public static function v4(): string
/**
* Generates the v3 UUID for a given string using the specified namespace.
*
* @param string $string The string to generate the UUID from.
* @param string $namespace The namespace to use for the UUID generation.
* @param string $namespace The namespace to use for the hash generation.
* @param string $string The string to generate the hash for.
* @return string
* @throws UUIDException
*/
public static function v5(string $string, string $namespace): string
public static function v5(string $namespace, string $string): string
{
$namespace = self::nsResolve($namespace);
if (!$namespace) {
Expand Down Expand Up @@ -134,13 +134,14 @@ public static function v6(string $node = null): string
/**
* Generates a version 7 UUID.
*
* @param DateTimeInterface|null $dateTime An optional DateTimeInterface object to create the UUID.
* @param string|null $node The node identifier. Defaults to null.
* @return string
* @throws Exception
*/
public static function v7(string $node = null): string
public static function v7(?DateTimeInterface $dateTime = null, string $node = null): string
{
$unixTsMs = (new DateTimeImmutable('now'))->format('Uv');
$unixTsMs = ($dateTime ?? new DateTimeImmutable('now'))->format('Uv');
if ($unixTsMs <= self::$unixTsMs) {
$unixTsMs = self::$unixTsMs + 1;
}
Expand Down

0 comments on commit d82cdc4

Please sign in to comment.