foamycastle/uuid

a complete uuid library

2.0 2024-11-27 04:08 UTC

Requires

• php: >=8.3

Requires (Dev)

• phpunit/phpunit: 11.4.0
• ramsey/uuid: 4.7.6

proprietary

• Aaron Sollman

README

This generator is fully compliant with RFC9562.

Basic Use

$uuid=UUID::Make(UUID::Version1);
//$uuid can now be used a string.
echo $uuid;
//output: 9ecfcb86-8514-11ef-8000-f01898ea0078

The value of $uuid is persistent until the ::refresh() method is called.

$uuid->refresh();
echo $uuid;
//output 5d3299da-8517-11ef-8000-f01898ea0078

Batching

A series of UUID strings can be procured from the ::batch method. This method returns a Generator instance that can be used as an iterator or easily stuffed into an array.

$uuid=UUID::Make(UUID::Version1);
$batch=$uuid->batch(4);

$batch is now an instance of Generator ready to dispense up to 4 strings with the same timestamp being differentiated only by the counter field in the UUID string itself in order to remain unique.

print_r([...$batch]);
/*output:
Array
(
    [0] => 092ae780-8516-11ef-8000-f01898ea0078
    [1] => 092ae780-8516-11ef-8001-f01898ea0078
    [2] => 092ae780-8516-11ef-8002-f01898ea0078
    [3] => 092ae780-8516-11ef-8003-f01898ea0078
)
*/

If the value of the counter field exceeds the allowable number of strings with a certain timestamp, the timestamp will automatically refresh itself. In a version 1 UUID, the counter's maximum value is 16384.

    [0]     => 653232b6-8518-11ef-8000-f01898ea0078
        ...
    [16382] => 653232b6-8518-11ef-bffe-f01898ea0078
    [16383] => 653232b6-8518-11ef-bfff-f01898ea0078
    
    ---timestamp refresh, counter reset---
    
    [16384] => 65644de7-8518-11ef-8000-f01898ea0078
    [16385] => 65644de7-8518-11ef-8001-f01898ea0078