limanweb/uuid

Custom UUID generate and analyze functions

v1.1.1 2024-05-28 17:50 UTC

Requires

• php: ^7.2.0|^8.0
• nesbot/carbon: ^2.0

MIT

• Ilya Khondozhko

• uuid
• laravel

README

Description

Package provides any functions to generate and analyze UUID.

Structure of generated UUID

There used custom algorithm to generate UUID with next structure:

SSSSSSSS-UUUU-UAAA-EEEE-RRRRRRRRRRRR

• S - 8 hex digits is seconds value of UUID generating timestamp
• U - 5 hex digits is microseconds value of UUID generating timestamp
• A - 3 hex digits is custom application code
• E - 4 hex digits is custom entity code
• R - 12 hex digits is random value

What is entity and application codes?

You can define any integer entity code and/or application code when call genUuid(). This allows you to distinguish visually and programmatically between UUIDs created by different applications for different DB entities.

Installation

Run command to install a package into you project

composer require limanweb/uuid

Limanweb\Uuid\Support\Uuid functions

genUuid()

Syntax:

genUuid(int $entityCode = null, int $appCode = null) : string

Returns UUID-string.

Params:

• $entityCode - custom integer code of entity (is 0 by default). Max value is 65535
• $appCode - custom integer code of application (is 0 by default). Max value is 4095

Returns UUID string.

Example:

$uuid = \Limanweb\Uuid\Support\Uuid::genUuid(256, 16);
echo $uuid; // "5ec004c4-0db2-0010-0100-a08cc1dd9a2b"

getUuidTimestamp()

Syntax:

getUuidTimestamp(string $uuid, string $format = 'Carbon') : mixed

Retrieve timestamp from UUID generated by genUuid().

Params:

• $uuid - analyzed UUID;
• $format - format of returning timestamp value. You can use one of tree variants:
  • Carbon (default) to get timestamp as \Carbon\Carbon object;
  • DateTime to get timestamp as \DateTime object;
  • date format string used for format() to get timestamp as formatted string. For example: 'Y-m-d H:i:s.u'

Example:

$uuid = "5ec004c4-0db2-0010-0100-a08cc1dd9a2b";

$ts = \Limanweb\Uuid\Support\Uuid::getUuidTimestamp($uuid, "Y-m-d H:i:s.u");

echo $ts; // "2020-05-16 18:20:36.056096"	

getUuidAppCode()

Syntax:

getUuidAppCode(string $uuid) : int

Retrieve application code from UUID generated by genUuid().

Params:

• $uuid - analyzed UUID;

Example:

$uuid = "5ec004c4-0db2-0010-0100-a08cc1dd9a2b";

$appCode = \Limanweb\Uuid\Support\Uuid::getUuidAppCode($uuid);
echo $appCode; // 16

getUuidAppCode()

Syntax:

getUuidAppCode(string $uuid) : int

Retrieve application code from UUID generated by genUuid().

Params:

• $uuid - analyzed UUID;

Example:

$uuid = "5ec004c4-0db2-0010-0100-a08cc1dd9a2b";

$appCode = \Limanweb\Uuid\Support\Uuid::getUuidAppCode($uuid);
echo $appCode; // 256

Using trait UsesUuid

1. Add trait \Limanweb\Uuid\Models\Concerns\UsesUuids use declaration into models where primary key is UUID.

2. You can define $appCode and $entityCode protected properties in your model to generate model UUID-key with specific segments.

This trait

• overrides getIncrementing() and getKeyType() methods therefore you don't need to define properties $incrementing and $keyType;
• adds getAppCode() and getEntityCode() public methods;
• registers creating event handler to generate UUID and fill model key.

Example:

class MyModel extends Model
{
	use \Limanweb\Uuid\Models\Concerns\UsesUuids;
	
	protected $appCode = 16;	// 010
	protected $entityCode = 256;	// 0100
	
	...

All IDs generated for this model will match the pattern ########-####-#010-0100-############.