Snowflake

Snowflake#

Class: Infocyph\\UID\\Snowflake

Bit Layout#

Snowflake follows a 64-bit layout:

  • 41 bits timestamp (ms from custom epoch)

  • 5 bits datacenter

  • 5 bits worker

  • 12 bits sequence

Generation#

<?php

use Infocyph\UID\Snowflake;

$id = Snowflake::generate();
$idFromNode = Snowflake::generate(datacenter: 1, workerId: 7);

Configuration Object#

Use Infocyph\\UID\\Configuration\\SnowflakeConfig for advanced control:

  • fixed datacenterId and workerId

  • nodeResolver callback

  • customEpoch (DateTimeInterface | int ms | parseable date string)

  • custom sequenceProvider

  • ClockBackwardPolicy (WAIT or THROW)

  • IdOutputType (STRING, INT, BINARY)

<?php

use Infocyph\UID\Configuration\SnowflakeConfig;
use Infocyph\UID\Enums\ClockBackwardPolicy;
use Infocyph\UID\Enums\IdOutputType;
use Infocyph\UID\Snowflake;

$config = new SnowflakeConfig(
    datacenterId: 2,
    workerId: 3,
    customEpoch: '2020-01-01 00:00:00',
    clockBackwardPolicy: ClockBackwardPolicy::WAIT,
    outputType: IdOutputType::STRING,
);

$id = Snowflake::generateWithConfig($config);

Validation and Parsing#

<?php

use Infocyph\UID\Snowflake;

Snowflake::isValid($id);
$parsed = Snowflake::parse($id);

parse() output:

  • time (DateTimeImmutable)

  • sequence (int)

  • worker_id (int)

  • datacenter_id (int)

Custom Epoch APIs#

  • Snowflake::setStartTimeStamp('2020-01-01 00:00:00')

  • Snowflake::parseWithEpoch($id, $epochMs)

Binary and Alternate Bases#

  • Snowflake::toBytes($id) / Snowflake::fromBytes($bytes)

  • Snowflake::toBase($id, $base) / Snowflake::fromBase($encoded, $base)

Supported bases: 16, 32, 36, 58, 62.

Exception Types#

  • Infocyph\\UID\\Exceptions\\SnowflakeException

  • Infocyph\\UID\\Exceptions\\FileLockException