Bits

Bits is a PHP library for generating unique 64-bit identifiers for use in distributed computing. You can use Bits to create Twitter Snowflake IDs, Sonyflake IDs, or any other unique ID that uses bit sequences.

Installation

composer require glhd/bits

Usage

To get a new snowflake ID, simply call Snowflake::make(). This returns a new Snowflake object:

class Snowflake
{
    public readonly int $timestamp;
    public readonly int $datacenter_id;
    public readonly int $worker_id;
    public readonly int $sequence;
    
    public function id(): int;
    public function is(Snowflake $other): bool;
}

You can also use the snowflake() or sonyflake() global helper functions, if you prefer.

All Bits IDs implement __toString() and the Laravel Query\Expression interface so that you can easily pass them around without juggling types.

Usage with Eloquent Models

Bits provides a HasSnowflakes trait that behaves the same as Eloquent’s HasUuids and HasUlids traits. Simply add HasSnowflakes to your model, and whenever they're inserted or upserted, and new Snowflake will be generated for you.

You can also use Snowflake or Sonyflake as in your Eloquent $casts array to have that attribute automatically cast to a Bits instance.

use Glhd\Bits\Database\HasSnowflakes;
use Glhd\Bits\Snowflake;
use Illuminate\Database\Eloquent\Model;

class Example extends Model
{
    // Auto-generate Snowflake for new models
    use HasSnowflakes;
    
    // Any attribute can be cast to a `Snowflake` (or `Sonyflake`)
    protected $casts = [
        'id' => Snowflake::class,
    ];
}

$example = Example::create();

$example->id instanceof Snowflake; // true

echo $example->id; // 65898467809951744

About 64-bit Unique IDs

Snowflake format

0 0000001100100101110101100110111100101011 01011 01111 000000011101
┳ ━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━ ━━━┳━ ━┳━━━ ━┳━━━━━━━━━━
┗━ unused bit     ┗━ timestamp (41)           ┃   ┃     ┗━ sequence (12)
                              datacenter (5) ━┛   ┗━ worker (5)

Sonyflake format

0 000000011001001011101011001101111001010 11010110 1111000000011101
┳ ━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━┳━ ━┳━━━━━━━━━━━━━━
┗━ sign   ┗ timestamp (39)         sequence (8) ┛   ┗ machine (16)

Both of these IDs are represented by the same 64-bit integer, 56705782302306333, but convey different metadata. Depending on your scale and distribution needs, you may find one or the other format preferable, or choose to implement your own custom format.

Bits lets generate any kind of 64-bit unique ID you'd like, in the way that makes the most sense for your use-case.

danmatthews / bits