Bits

https://github.com/glhd/bits
Admin
Bits is a PHP library for generating unique 64-bit identifiers for use in distributed computing. It...
Tokens:59,658
Snippets:477
Trust Score:6.9
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### Example: Using snowflake() helper

Source: https://github.com/glhd/bits

Shows how to get the factory, generate a new Snowflake, and parse an existing ID using the snowflake() helper.

```php
$factory   = snowflake();            // MakesSnowflakes
$new_id    = snowflake()->make();    // Snowflake
$parsed    = snowflake(65898467809951744); // Snowflake
```

--------------------------------

### Example config/bits.php

Source: https://github.com/glhd/bits

Example configuration file for the Bits package. Defines the format, epoch, worker ID, and datacenter ID, using environment variables with defaults.

```php
// config/bits.php
return [
    'format'        => 'snowflake',
    'epoch'         => env('BITS_EPOCH', '2023-01-01'),
    'worker_id'     => env('BITS_WORKER_ID'),
    'datacenter_id' => env('BITS_DATACENTER_ID'),
];
```

--------------------------------

### Example: Using sonyflake() helper

Source: https://github.com/glhd/bits

Shows how to get the factory and parse an existing Sonyflake ID using the sonyflake() helper.

```php
$factory = sonyflake();               // MakesSonyflakes
$parsed  = sonyflake(56705782302306333); // Sonyflake
```

--------------------------------

### Example .env for Bits

Source: https://github.com/glhd/bits

Environment variables used by the example config/bits.php. Sets worker ID, datacenter ID, and epoch.

```dotenv
# .env
BITS_WORKER_ID=7
BITS_DATACENTER_ID=2
BITS_EPOCH=2021-06-15
```

--------------------------------

### SnowflakeFactory usage example

Source: https://github.com/glhd/bits

Shows how to instantiate SnowflakeFactory with an epoch, datacenter_id, worker_id, config, and an InMemorySequenceResolver. Then creates a snowflake and uses firstForTimestamp() to get the smallest ID at a past timestamp, which can be used as a 'created after' filter.

```php
use Glhd\Bits\Factories\SnowflakeFactory;
use Glhd\Bits\SequenceResolvers\InMemorySequenceResolver;

$factory = new SnowflakeFactory(
    epoch: now()->startOfDay(),
    datacenter_id: 3,
    worker_id: 15,
    config: app(SnowflakesConfig::class),
    sequence: new InMemorySequenceResolver(),
);

$snowflake = $factory->make();
// Later timestamps produce larger IDs, so this works as a "created after" filter:
$since = $factory->firstForTimestamp(now()->subHour());
```

--------------------------------

### Snowflake::make() usage example

Source: https://github.com/glhd/bits

Creates a Snowflake for the current moment and shows how to access its timestamp, datacenter_id, worker_id, sequence, and id() properties. The comment shows example values.

```php
use Glhd\Bits\Snowflake;

$snowflake = Snowflake::make();
// $snowflake->timestamp     -> e.g. 65898467
// $snowflake->datacenter_id -> e.g. 3
// $snowflake->worker_id     -> e.g. 7
// $snowflake->sequence      -> e.g. 0
echo $snowflake->id(); // 65898467809951744
```

--------------------------------

### SonyflakeFactory usage example

Source: https://github.com/glhd/bits

Shows how to instantiate SonyflakeFactory with an epoch, machine ID, config, and an in-memory sequence resolver, then generate a new Sonyflake with make().

```php
use Glhd\Bits\Factories\SonyflakeFactory;
use Glhd\Bits\SequenceResolvers\InMemorySequenceResolver;

$factory = new SonyflakeFactory(
    epoch: now()->startOfDay(),
    machine_id: 1024,
    config: app(SonyflakesConfig::class),
    sequence: new InMemorySequenceResolver(),
);

$sonyflake = $factory->make();
```

--------------------------------

### Install Bits via Composer

Source: https://github.com/glhd/bits/blob/main/README.md

Use Composer to install the Bits library for generating unique 64-bit identifiers.

```shell
composer require glhd/bits
```

--------------------------------

### GenericFactory usage example

Source: https://github.com/glhd/bits

Example creating a GenericFactory with a custom layout and generating bits. Uses InMemorySequenceResolver and firstForTimestamp for the first ID of the hour.

```php
use Glhd\Bits\Config\GenericConfig;
use Glhd\Bits\Config\Segment;
use Glhd\Bits\Config\WorkerIds;
use Glhd\Bits\Factories\GenericFactory;
use Glhd\Bits\SequenceResolvers\InMemorySequenceResolver;
use Illuminate\Support\Collection;

$factory = new GenericFactory(
    epoch: now()->startOfDay(),
    ids: new WorkerIds(7),
    config: new GenericConfig(
        precision: 6,
        unit: 1,
        segments: new Collection([
            Segment::timestamp('timestamp', 50),
            Segment::id('id', 4),
            Segment::sequence('sequence', 10),
        ]),
    ),
    sequence: new InMemorySequenceResolver(),
);

$bits = $factory->make();
$first_of_hour = $factory->firstForTimestamp(now()->startOfHour());
```

--------------------------------

### register() method declaration

Source: https://github.com/glhd/bits

Performs config merge, aliases, singletons, and factory setup in order.

```php
public function register()
```

--------------------------------

### Example: implementing your own resolver

Source: https://github.com/glhd/bits

Shows how to implement ResolvesSequences with a cache lock for multi-server deployments. Uses an atomic counter with a lock to safely increment and return the sequence.

```php
use Glhd\Bits\Contracts\ResolvesSequences;
use Illuminate\Support\Facades\Cache;

class LockedSequenceResolver implements ResolvesSequences
{
    public function next(int $timestamp): int
    {
        // e.g. an atomic counter with a lock for multi-server deployments
        return Cache::lock("seq:{$timestamp}", 10)->get(function () use ($timestamp) {
            return Cache::increment("seq:{$timestamp}") - 1;
        });
    }
}
```

--------------------------------

### Bits::toCarbon() usage example

Source: https://github.com/glhd/bits

Shows how to get a Carbon instance of the ID's timestamp and use it as a query boundary with Snowflake IDs.

```php
use Glhd\Bits\Snowflake;

$snowflake = Snowflake::make();
$created_at = $snowflake->toCarbon(); // Carbon instance of the ID's timestamp

// Use as a query boundary:
User::where('id', '>', Snowflake::make()->id())
    ->where('id', '<', app(MakesSnowflakes::class)->firstForTimestamp(now()));
```

--------------------------------

### Sonyflake id() usage example

Source: https://github.com/glhd/bits

Shows how to create a Sonyflake instance and retrieve its 64-bit integer ID using the id() method.

```php
use Glhd\Bits\Sonyflake;

$sonyflake = Sonyflake::make();
$id = $sonyflake->id(); // 64-bit integer
```

--------------------------------

### setTestNow usage examples

Source: https://github.com/glhd/bits

Shows three ways to control the clock: freeze to a specific time, use a closure resolver, or revert to real time. The first freezes the clock for one instant, the second uses a closure, and the third clears the resolver.

```php
$factory->setTestNow(now()->addMilliseconds(2)); // freeze the clock for one instant
$factory->setTestNow(fn() => now());             // closure resolver
$factory->setTestNow();                          // back to real time
```

--------------------------------

### Example: Using snowflake_id() helper

Source: https://github.com/glhd/bits

Shows generating a new 64-bit integer Snowflake ID ready to store, e.g., for a team_id column.

```php
$user->team_id = snowflake_id(); // new 64-bit int, ready to store
```

--------------------------------

### Bits::make() example

Source: https://github.com/glhd/bits

Creates a new Bits instance for the current moment and prints its ID. The output is a 64-bit integer like 93823254528.

```php
use Glhd\Bits\Bits;

$bits = Bits::make();
echo $bits->id(); // 93823254528

```

--------------------------------

### Blueprint snowflake macros example

Source: https://github.com/glhd/bits

Shows usage of the snowflakeId and snowflake macros in a schema definition. snowflakeId creates an unsignedBigInteger primary key, snowflake creates an unsignedBigInteger column.

```php
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('users', function (Blueprint $table) {
    $table->snowflakeId();          // unsignedBigInteger('id')->primary()
    $table->snowflake('team_id');   // unsignedBigInteger('team_id')
});
```

--------------------------------

### Bits::coerce() example

Source: https://github.com/glhd/bits

Coerces an integer, a numeric string, and an existing Bits instance. The existing instance is returned as-is.

```php
use Glhd\Bits\Bits;

$from_int    = Bits::coerce(93823254528);
$from_string = Bits::coerce('93823254528');
$from_bits   = Bits::coerce($from_int); // returned as-is

```

--------------------------------

### TestingSequenceResolver usage example

Source: https://github.com/glhd/bits

Example of using TestingSequenceResolver with a sequence value near the snowflake limit. When the sequence reaches maxSequence, the factory sleeps and retries.

```php
use Glhd\Bits\SequenceResolvers\TestingSequenceResolver;

$sequence = 4094; // simulate being near the snowflake sequence limit
$resolver = new TestingSequenceResolver($sequence);

$resolver->next(100); // 4094
$resolver->next(100); // 4095 (maxSequence for snowflakes -> factory sleeps and retries)
```

--------------------------------

### CacheSequenceResolver usage example

Source: https://github.com/glhd/bits

Example of instantiating CacheSequenceResolver with a Redis cache store and calling next() twice for the same timestamp. The first call returns 0 and the second returns 1, demonstrating the zero-based sequence behavior.

```php
use Glhd\Bits\SequenceResolvers\CacheSequenceResolver;
use Illuminate\Support\Facades\Cache;

$resolver = new CacheSequenceResolver(Cache::store('redis'));

$seq = $resolver->next(93823254528); // 0
$seq = $resolver->next(93823254528); // 1
```

--------------------------------

### BitsCast usage example with Snowflake and Sonyflake casts

Source: https://github.com/glhd/bits

Shows how to configure Eloquent casts using Snowflake and Sonyflake classes. The 'id' cast uses the default snowflake factory, while 'photo_id' forces the sonyflake factory. After creating a User, $user->id is a Snowflake instance and $user->id->id() returns the 64-bit integer.

```php
use Glhd\Bits\Snowflake;
use Glhd\Bits\Sonyflake;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $casts = [
        'id'        => Snowflake::class,                  // snowflake-backed cast
        'photo_id'  => [Sonyflake::class, 'sonyflake'],   // force sonyflake factory
    ];
}

$user = User::create();
$user->id instanceof Snowflake; // true
$user->id->id();                // the 64-bit int
```

--------------------------------

### Sonyflake::make() static factory method

Source: https://github.com/glhd/bits

Creates a new Sonyflake for the current moment using app(MakesSonyflakes::class)->make(). The machine ID comes from the bits.worker_id config value. Example shows accessing timestamp, sequence, machine_id, and id().

```php
public static function make(): static
```

```php
use Glhd\Bits\Sonyflake;

$sonyflake = Sonyflake::make();
// $sonyflake->timestamp  -> e.g. 3379928010
// $sonyflake->sequence   -> e.g. 214
// $sonyflake->machine_id -> e.g. 61469
echo $sonyflake->id(); // 56705782302306333
```

--------------------------------

### InMemorySequenceResolver usage example

Source: https://github.com/glhd/bits

Example of using InMemorySequenceResolver. The sequence resets to 0 when the timestamp changes (e.g., from 100 to 101).

```php
use Glhd\Bits\SequenceResolvers\InMemorySequenceResolver;

$resolver = new InMemorySequenceResolver();

$resolver->next(100); // 0
$resolver->next(100); // 1
$resolver->next(100); // 2
$resolver->next(101); // 0  (new timestamp resets)
```

--------------------------------

### Sonyflake timestamp extraction example

Source: https://github.com/glhd/bits

Demonstrates extracting the timestamp from a Sonyflake ID using toCarbon(). The config's unit = 10 means the timestamp value is multiplied by 10 ms when converting back, so microseconds are rounded to the nearest 10ms.

```php
use Glhd\Bits\Sonyflake;

$sonyflake = Sonyflake::fromId(56705782302306333);

$sonyflake->toCarbon()->format('Y-m-d H:i:s.u');
// 10ms-precision, so microseconds are rounded to the nearest 10ms
```

--------------------------------

### Bits::is() equality example

Source: https://github.com/glhd/bits

Shows that is() returns true for two Snowflakes with the same ID but false when comparing a Snowflake to a Sonyflake with the same numeric ID.

```php
use Glhd\Bits\Snowflake;
use Glhd\Bits\Sonyflake;

$a = Snowflake::fromId(1537200202186752);
$b = Snowflake::fromId(1537200202186752);
$c = Sonyflake::fromId(1537200202186752);

$a->is($b); // true
$a->is($c); // false
```

--------------------------------

### Snowflake id() usage example

Source: https://github.com/glhd/bits

Creates a Snowflake and retrieves its 64-bit integer ID. Later timestamps produce larger IDs, so comparing IDs can sort by time.

```php
use Glhd\Bits\Snowflake;

$snowflake = Snowflake::make();
$id = $snowflake->id(); // 64-bit integer

// Sortable by time: later timestamps produce larger IDs
$later = Snowflake::make();
$later->id() > $id; // true
```

--------------------------------

### GenericConfig::parse()

Source: https://github.com/glhd/bits

Splits a combined 64-bit integer back into per-segment values by masking and shifting. Example shows parsing 1537200202186752 with SnowflakesConfig returning [0, 93823254528, 0, 0, 0].

```php
public function parse(int $id): array
```

```php
$config = new SnowflakesConfig();
$config->parse(1537200202186752); // [0, 93823254528, 0, 0, 0] (pad, ts, dc, worker, seq)
```

--------------------------------

### BitsCast get() method

Source: https://github.com/glhd/bits

Returns null when the stored value is null; otherwise returns $this->factory->coerce($value). The $model, $key, and $attributes parameters are unused.

```php
public function get($model, string $key, $value, array $attributes)
```

--------------------------------

### Bits::fromId() example

Source: https://github.com/glhd/bits

Parses an existing 64-bit ID and shows the resulting segment values. The timestamp segment is 93823254528, the id segment is 0, and the sequence segment is 0.

```php
use Glhd\Bits\Bits;

$bits = Bits::fromId(1537200202186752);
// $bits->values[0] === 93823254528 (timestamp segment)
// $bits->values[1] === 0            (id segment)
// $bits->values[2] === 0            (sequence segment)

```

--------------------------------

### Example: Using HasSnowflakes trait in a model

Source: https://github.com/glhd/bits

Shows a model using the HasSnowflakes trait with a Snowflake cast on the id. Creating a model generates a Snowflake ID that can be echoed as an integer.

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

class Example extends Model
{
    use HasSnowflakes;

    protected $casts = [
        'id' => Snowflake::class,
    ];
}

$example = Example::create();
$example->id instanceof Snowflake; // true
echo $example->id; // 65898467809951744
```

--------------------------------

### Extracting timestamp from Snowflake ID

Source: https://github.com/glhd/bits/blob/main/README.md

Gets the creation timestamp from a Snowflake ID using toCarbon() instead of reading created_at.

```php
// Instead of:
$created_at = $user->created_at;

// You can do (assuming User::id is cast to a Snowflake object)
$created_at = $user->id->toCarbon();
```

--------------------------------

### Bits::castUsing() example with Eloquent casts

Source: https://github.com/glhd/bits

Shows how to use Bits subclasses in an Eloquent model's $casts array. The 'id' attribute uses the snowflake factory, while 'avatar_id' uses the sonyflake factory via the 'sonyflake' argument.

```php
use Glhd\Bits\Snowflake;
use Glhd\Bits\Sonyflake;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $casts = [
        'id'          => Snowflake::class,             // snowflake factory
        'avatar_id'   => [Sonyflake::class, 'sonyflake'], // sonyflake factory
    ];
}

```

--------------------------------

### boot() method declaration

Source: https://github.com/glhd/bits

Requires helpers.php, calls bootConfig(), and registers Blueprint macros for snowflake and snowflakeId columns.

```php
public function boot()
```

--------------------------------

### Registering synthesizers in AppServiceProvider::boot()

Source: https://github.com/glhd/bits

Register one or both synthesizers via Livewire::propertySynthesizer(). Register SnowflakeSynth for snowflakes only, or BitsSynth for Sonyflakes or custom Bits variants.

```php
use Glhd\Bits\Support\Livewire\BitsSynth;
use Glhd\Bits\Support\Livewire\SnowflakeSynth;
use Livewire\Livewire;

public function boot(): void
{
    // Snowflakes only:
    Livewire::propertySynthesizer(SnowflakeSynth::class);

    // Sonyflakes or custom Bits variants:
    Livewire::propertySynthesizer(BitsSynth::class);
}
```

--------------------------------

### bootConfig() method declaration

Source: https://github.com/glhd/bits

Publishes the package config to config/bits.php under the bits-config tag.

```php
protected function bootConfig(): self
```

--------------------------------

### Snowflake::fromId() usage example

Source: https://github.com/glhd/bits

Parses a Snowflake ID and shows that the datacenter_id, worker_id, and sequence are all 0 for the given ID.

```php
use Glhd\Bits\Snowflake;

$snowflake = Snowflake::fromId(1537200202186752);
// $snowflake->datacenter_id === 0
// $snowflake->worker_id     === 0
// $snowflake->sequence      === 0
```

--------------------------------

### GenericFactory methods implementing MakesBits

Source: https://github.com/glhd/bits

Lists all five methods that implement MakesBits, including make(), makeFromTimestamp(), firstForTimestamp(), fromId(), and coerce().

```php
public function make(): Bits                                                    // src/Factories/GenericFactory.php:27-34
public function makeFromTimestamp(CarbonInterface $timestamp): Bits              // src/Factories/GenericFactory.php:36-48
public function firstForTimestamp(CarbonInterface $timestamp): Bits              // src/Factories/GenericFactory.php:50-61
public function fromId(int|string $id): Bits                                    // src/Factories/GenericFactory.php:63-68
public function coerce(int|string|Bits $value): Bits                            // src/Factories/GenericFactory.php:70-77
```

--------------------------------

### Bits::jsonSerialize() JSON output example

Source: https://github.com/glhd/bits

Shows that json_encode() on a Snowflake returns a JSON string with the ID as a string, and toJson() echoes the same.

```php
use Glhd\Bits\Snowflake;

$snowflake = Snowflake::make();

json_encode($snowflake); // "\"65898467809951744\""
echo $snowflake->toJson(); // same
```

--------------------------------

### SonyflakeFactory constructor

Source: https://github.com/glhd/bits

Constructor accepts an epoch, machine ID (0-65535), SonyflakesConfig, and a sequence resolver. All parameters are required.

```php
public function __construct(
    CarbonInterface $epoch,
    public readonly int $machine_id,
    SonyflakesConfig $config,
    ResolvesSequences $sequence,
)
```

--------------------------------

### Catching errors in consumer code

Source: https://github.com/glhd/bits

Shows how to catch standard exceptions thrown by Bits factories and methods. Includes catching InvalidArgumentException for bad configuration and sequence exhaustion, and RuntimeException for 32-bit platform issues.

```php
use Glhd\Bits\Factories\SnowflakeFactory;
use Glhd\Bits\SequenceResolvers\InMemorySequenceResolver;
use InvalidArgumentException;
use RuntimeException;

// 1. Bad configuration fails fast at construction time:
try {
    $factory = new SnowflakeFactory(
        epoch: now()->addDay(),      // future epoch!
        datacenter_id: 1,
        worker_id: 15,
        config: app(SnowflakesConfig::class),
        sequence: new InMemorySequenceResolver(),
    );
} catch (InvalidArgumentException $e) {
    // "Trying to use "..." as epoch, but it is currently "..." ..."
    report($e);
}

// 2. Sequence exhaustion on a fixed timestamp:
try {
    $factory->makeFromTimestamp($some_instant);
} catch (InvalidArgumentException $e) {
    if ($e->getMessage() === 'Hit sequence limit for timestamp.') {
        // More than 4095 IDs requested for a single millisecond (snowflake)
    }
}

// 3. 32-bit platforms:
try {
    $factory = new SnowflakeFactory(...);
} catch (RuntimeException $e) {
    // "Bits requires 64-bit integer support."
}
```

--------------------------------

### Validation failures propagate through static entry points

Source: https://github.com/glhd/bits

Shows that configuration errors like an unknown format surface through static methods like Snowflake::make(), throwing InvalidArgumentException.

```php
try {
    $id = Snowflake::make();
} catch (InvalidArgumentException $e) {
    // e.g. "Unknown bits format: 'weird'"
}
```

--------------------------------

### BitsFactory constructor with epoch, config, and sequence

Source: https://github.com/glhd/bits

Constructor accepts an epoch CarbonInterface, a Configuration, and a ResolvesSequences. It runs validateConfiguration(), which throws RuntimeException for 64-bit support and InvalidArgumentException for a future epoch.

```php
public function __construct(
    public readonly CarbonInterface $epoch,
    protected Configuration $config,
    protected ResolvesSequences $sequence,
)
```

--------------------------------

### Sonyflake::__construct()

Source: https://github.com/glhd/bits

Creates a new Sonyflake instance with the given timestamp, sequence, machine ID, epoch, and optional config. Passes the values to the parent constructor and throws an InvalidArgumentException if any segment value exceeds its range.

```APIDOC
## Constructor

### Description
Creates a new Sonyflake instance with the given timestamp, sequence, machine ID, epoch, and optional config.

### Method
Constructor

### Signature
```php
public function __construct(
    public readonly int $timestamp,
    public readonly int $sequence,
    public readonly int $machine_id,
    CarbonInterface $epoch,
    ?SonyflakesConfig $config = null,
)
```

### Parameters
- **$timestamp** (int) - Required - 10 ms units since the epoch (0–2^40-1)
- **$sequence** (int) - Required - 0–255
- **$machine_id** (int) - Required - 0–65535
- **$epoch** (Carbon\CarbonInterface) - Required - Epoch the timestamp is relative to
- **$config** (?SonyflakesConfig) - Optional - Default: `app(SonyflakesConfig::class)` - Optional custom sonyflake layout config

### Throws
- **InvalidArgumentException** - if any segment value exceeds its range
```

--------------------------------

### SonyflakeFactory method signatures

Source: https://github.com/glhd/bits

Lists the public methods: make(), makeFromTimestamp(), firstForTimestamp(), fromId(), and coerce(). makeFromTimestamp() throws InvalidArgumentException with message 'Hit sequence limit for timestamp.' when the sequence limit is reached.

```php
public function make(): Sonyflake                                   // src/Factories/SonyflakeFactory.php:29-34
public function makeFromTimestamp(CarbonInterface $timestamp): Sonyflake  // src/Factories/SonyflakeFactory.php:36-46
public function firstForTimestamp(CarbonInterface $timestamp): Sonyflake  // src/Factories/SonyflakeFactory.php:48-53
public function fromId(int|string $id): Sonyflake                   // src/Factories/SonyflakeFactory.php:55-60
public function coerce(int|string|Bits $value): Sonyflake           // src/Factories/SonyflakeFactory.php:62-71
```

--------------------------------

### Registering Livewire synthesizers for Snowflake and Bits

Source: https://github.com/glhd/bits/blob/main/README.md

Registers SnowflakeSynth for Snowflakes or BitsSynth for any Bits variant in AppServiceProvider.

```php
use Glhd\Bits\Support\Livewire\SnowflakeSynth;
use Glhd\Bits\Support\Livewire\BitsSynth;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // If only using Snowflakes:
        Livewire::propertySynthesizer(SnowflakeSynth::class);
        
        // If using Sonyflakes or a custom Bits variant:
        Livewire::propertySynthesizer(BitsSynth::class);
    }
}
```

--------------------------------

### SonyflakesConfig constructor

Source: https://github.com/glhd/bits

Constructor with no arguments. Uses millisecond precision with unit of 10 (classic Sonyflake scheme). The 16-bit ID segment is exposed as machine_id on the Sonyflake class. Registered as a container singleton.

```php
parent::__construct(
    precision: 3,
    unit: 10,
    segments: new Collection([
        Segment::timestamp(label: 'timestamp', length: 40),
        Segment::sequence(label: 'sequence', length: 8),
        Segment::id(label: 'datacenter', length: 16),
    ]),
);
```

--------------------------------

### Snowflake::coerce() usage example

Source: https://github.com/glhd/bits

Coerces an integer, string, and a generic Bits instance into a Snowflake. The generic Bits is converted to a Snowflake of the same value, and the id() comparison returns true.

```php
use Glhd\Bits\Bits;
use Glhd\Bits\Snowflake;

$snowflake = Snowflake::coerce(1537200202186752);
$also      = Snowflake::coerce('1537200202186752');

// Convert a generic Bits (custom layout) to a Snowflake of the same value:
$generic = Bits::make();
$as_snowflake = Snowflake::coerce($generic);
$as_snowflake->id() === $generic->id(); // true
```

--------------------------------

### SnowflakeFactory methods signatures

Source: https://github.com/glhd/bits

Lists the public methods of SnowflakeFactory: make(), makeFromTimestamp(), firstForTimestamp(), fromId(), and coerce(). Each method returns a Snowflake instance.

```php
public function make(): Snowflake                                   // src/Factories/SnowflakeFactory.php:30-35
public function makeFromTimestamp(CarbonInterface $timestamp): Snowflake  // src/Factories/SnowflakeFactory.php:37-47
public function firstForTimestamp(CarbonInterface $timestamp): Snowflake  // src/Factories/SnowflakeFactory.php:49-54
public function fromId(int|string $id): Snowflake                   // src/Factories/SnowflakeFactory.php:56-61
public function coerce(int|string|Bits $value): Snowflake           // src/Factories/SnowflakeFactory.php:63-72
```

--------------------------------

### Sonyflake::make()

Source: https://github.com/glhd/bits

Creates a new Sonyflake for the current moment using the configured factory. The machine ID is sourced from the bits.worker_id config value.

```APIDOC
## Sonyflake::make()

### Description
Creates a new Sonyflake for the current moment via `app(MakesSonyflakes::class)->make()`. The machine ID comes from the `bits.worker_id` config value.

### Method
`public static function make(): static`

### Parameters
None.

### Response
Returns a new `Sonyflake` instance with `timestamp`, `sequence`, and `machine_id` properties populated.

### Request Example
```php
use Glhd\Bits\Sonyflake;

$sonyflake = Sonyflake::make();
// $sonyflake->timestamp  -> e.g. 3379928010
// $sonyflake->sequence   -> e.g. 214
// $sonyflake->machine_id -> e.g. 61469
echo $sonyflake->id(); // 56705782302306333
```
```

--------------------------------

### Extract timestamp from Snowflake ID

Source: https://github.com/glhd/bits

Shows how to recover the timestamp from a Snowflake instance using toCarbon() and toDateTime(). The example creates a Snowflake from an ID and formats the timestamp with microseconds. toDateTime() returns a DateTimeImmutable in the epoch's timezone.

```php
use Glhd\Bits\Snowflake;

$snowflake = Snowflake::fromId(65898467809951744);

$snowflake->toCarbon()->format('Y-m-d H:i:s.u');
$snowflake->toDateTime(); // DateTimeImmutable in the epoch's timezone
```

--------------------------------

### Sonyflake constructor signature

Source: https://github.com/glhd/bits

Defines the constructor for the Sonyflake class. Requires timestamp, sequence, machine_id, and epoch; config is optional and defaults to app(SonyflakesConfig::class). Throws InvalidArgumentException if any segment value exceeds its range.

```php
public function __construct(
    public readonly int $timestamp,
    public readonly int $sequence,
    public readonly int $machine_id,
    CarbonInterface $epoch,
    ?SonyflakesConfig $config = null,
)
```

--------------------------------

### SonyflakeFactory::__construct

Source: https://github.com/glhd/bits

Creates a new SonyflakeFactory instance with the given epoch, machine ID, configuration, and sequence resolver. This constructor is used to initialize the factory for generating Sonyflake IDs.

```APIDOC
## Constructor

### Description
Creates a new SonyflakeFactory instance with the given epoch, machine ID, configuration, and sequence resolver.

### Method
`__construct`

### Parameters
- `$epoch` (CarbonInterface) - Required - Epoch
- `$machine_id` (int) - Required - 0–65535
- `$config` (SonyflakesConfig) - Required - Sonyflake layout
- `$sequence` (ResolvesSequences) - Required - Sequence source

### Example
```php
use Glhd\Bits\Factories\SonyflakeFactory;
use Glhd\Bits\SequenceResolvers\InMemorySequenceResolver;

$factory = new SonyflakeFactory(
    epoch: now()->startOfDay(),
    machine_id: 1024,
    config: app(SonyflakesConfig::class),
    sequence: new InMemorySequenceResolver(),
);
```
```

--------------------------------

### Constructor

Source: https://github.com/glhd/bits

Creates a new Bits instance with per-segment values, a configuration, and an epoch. Validates values against the config and stores them as a Collection.

```APIDOC
## Constructor

### Description
Creates a new Bits instance with per-segment values, a configuration, and an epoch. Validates values against the config and stores them as a Collection.

### Method
Constructor

### Signature
```php
public function __construct(
    array $values,
    protected Configuration $config,
    protected CarbonInterface $epoch,
)
```

### Parameters
- `$values` (array) - Required - Per-segment values, in segment order (same order as the config's `segments` collection)
- `$config` (Configuration) - Required - The bit-layout config that validates, combines, and parses values
- `$epoch` (CarbonInterface) - Required - The epoch timestamp IDs are relative to; used for timestamp reconstruction

### Throws
- `InvalidArgumentException` when a value fails segment validation
```

--------------------------------

### BitsFactory::__construct()

Source: https://github.com/glhd/bits

Constructor for the abstract BitsFactory class. Initializes the factory with an epoch, configuration, and sequence resolver, and validates the configuration.

```APIDOC
## BitsFactory::__construct()

### Description
Constructor for the abstract BitsFactory class. Initializes the factory with an epoch, configuration, and sequence resolver, and validates the configuration.

### Method
Constructor

### Signature
```php
public function __construct(
    public readonly CarbonInterface $epoch,
    protected Configuration $config,
    protected ResolvesSequences $sequence,
)
```

### Parameters
- **$epoch** (CarbonInterface) - Required - Epoch all timestamps are relative to (must not be in the future)
- **$config** (Configuration) - Required - Bit-layout config
- **$sequence** (ResolvesSequences) - Required - Sequence source

### Exceptions
- **RuntimeException** - "Bits requires 64-bit integer support." when `PHP_INT_SIZE < 8`
- **InvalidArgumentException** - "Trying to use \"{epoch}\" as epoch, but it is currently \"{now}\" (Bits epoch cannot be in the future)." when the epoch is in the future
```

--------------------------------

### GenericConfig constructor

Source: https://github.com/glhd/bits

Constructor for GenericConfig. Requires precision (0-6), unit (base-precision units per tick), and a Collection of segments whose lengths must sum to exactly 64. Throws InvalidArgumentException for invalid parameters or bit total not equal to 64.

```php
public function __construct(
    protected int $precision,
    protected int $unit,
    protected Collection $segments,
)
```

--------------------------------

### Segment static factory methods

Source: https://github.com/glhd/bits

Creates a named, typed segment for a 64-bit ID layout. `id()` makes an ID segment, `timestamp()` a timestamp segment, and `sequence()` a sequence segment; each takes a label and length in bits.

```php
public static function id(string $label, int $length): static          // src/Config/Segment.php:13
public static function timestamp(string $label, int $length): static   // src/Config/Segment.php:18
public static function sequence(string $label, int $length): static    // src/Config/Segment.php:23
```

--------------------------------

### GenericConfig::__construct

Source: https://github.com/glhd/bits

Creates a new GenericConfig instance with the given precision, unit, and segments. Validates the configuration and throws an InvalidArgumentException if invalid.

```APIDOC
## GenericConfig::__construct

### Description
Creates a new GenericConfig instance with the given precision, unit, and segments. Validates the configuration and throws an InvalidArgumentException if invalid.

### Method
__construct

### Signature
```php
public function __construct(
    protected int $precision,
    protected int $unit,
    protected Collection $segments,
)
```

### Parameters
- **$precision** (int) - Required - Number of decimal digits of sub-second precision kept in the timestamp (0–6)
- **$unit** (int) - Required - Number of base-precision units per timestamp tick
- **$segments** (Illuminate\Support\Collection) - Required - `Collection<int, Segment>` of segments; lengths must sum to exactly 64

### Throws
- **InvalidArgumentException** - for invalid precision, unit, segment types, segment count, or a bit total ≠ 64
```

--------------------------------

### Sonyflake::fromId() static factory method

Source: https://github.com/glhd/bits

Parses an existing Sonyflake integer back into a Sonyflake with segments split into public properties.

```php
public static function fromId(int|string $id): static
```

```php
use Glhd\Bits\Sonyflake;

$sonyflake = Sonyflake::fromId(56705782302306333);
// $sonyflake->timestamp  === 3379928010
// $sonyflake->sequence   === 214
// $sonyflake->machine_id === 61469
```

--------------------------------

### GenericConfig::organize()

Source: https://github.com/glhd/bits

Maps worker IDs, timestamp, and sequence into per-segment values in segment order. Requires the number of worker IDs plus 2 to equal the segment count. Throws InvalidArgumentException with message 'Expected {n} segments but received {m}.'

```php
public function organize(WorkerIds $ids, int $timestamp, int $sequence): array
```

--------------------------------

### SonyflakeFactory::firstForTimestamp

Source: https://github.com/glhd/bits

Generates the smallest Sonyflake at the given timestamp with sequence = 0 and machine_id = 0. This is useful for finding the first ID at a specific time.

```APIDOC
## firstForTimestamp()

### Description
Generates the smallest Sonyflake at the given timestamp with sequence = 0 and machine_id = 0.

### Method
`firstForTimestamp`

### Parameters
- `$timestamp` (CarbonInterface) - Required - The timestamp for which to generate the Sonyflake.

### Return Value
- `Sonyflake` - A Sonyflake instance with sequence = 0 and machine_id = 0.
```

--------------------------------

### SnowflakesConfig constructor

Source: https://github.com/glhd/bits

Constructor with no arguments. Sets millisecond precision (3), unit of 1, and segments summing to 64 bits. Registered as a container singleton aliased to Configuration.

```php
parent::__construct(
    precision: 3,
    unit: 1,
    segments: new Collection([
        Segment::id(label: 'pad', length: 1),
        Segment::timestamp(label: 'timestamp', length: 41),
        Segment::id(label: 'datacenter', length: 5),
        Segment::id(label: 'worker', length: 5),
        Segment::sequence(label: 'sequence', length: 12),
    ]),
);
```

--------------------------------

### BitsSynth

Source: https://github.com/glhd/bits

A generic Livewire synthesizer that stores the string ID plus the concrete class, and hydrates via the class's fromId() method. Works with Bits, Snowflake, Sonyflake, and any custom subclass.

```APIDOC
## BitsSynth

### Description
A generic Livewire synthesizer that stores the string ID plus the concrete class, and hydrates via the class's fromId() method. Works with Bits, Snowflake, Sonyflake, and any custom subclass.

### Class
`Glhd\Bits\Support\Livewire\BitsSynth`

### Methods

#### `match($target)`
- **Parameters**: `$target` (mixed) - The target value to check.
- **Returns**: `bool` - True when `$target` is an instance of `Bits`.

#### `dehydrate($target)`
- **Parameters**: `$target` (Bits) - The Bits instance to dehydrate.
- **Returns**: array - `[$target->jsonSerialize(), ['class' => $target::class]]`

#### `hydrate($value, $meta)`
- **Parameters**:
  - `$value` (mixed) - The serialized value.
  - `$meta` (array) - Metadata containing the class name.
- **Returns**: Bits - `$meta['class']::fromId($value)`

### Registration
Register via `Livewire::propertySynthesizer(BitsSynth::class)` in your `AppServiceProvider::boot()`.
```

--------------------------------

### GenericConfig::combine()

Source: https://github.com/glhd/bits

ORs each value into its segment's bit position to produce the combined 64-bit ID.

```php
public function combine(int ...$values): int
```

--------------------------------

### setTestNow method signature

Source: https://github.com/glhd/bits

Sets a custom time resolver for make(). Accepts a fixed CarbonInterface, a closure returning a time, or null to clear. Independent of Carbon::setTestNow(); when a CarbonInterface is passed, it is wrapped to return avoidMutation() copies.

```php
public function setTestNow(CarbonInterface|Closure|null $now_resolver = null): static
```

--------------------------------

### SnowflakeFactory constructor

Source: https://github.com/glhd/bits

Constructor for SnowflakeFactory. Requires an epoch, datacenter_id (0-31), worker_id (0-31), a SnowflakesConfig for layout, and a ResolvesSequences for sequence source.

```php
public function __construct(
    CarbonInterface $epoch,
    public readonly int $datacenter_id,
    public readonly int $worker_id,
    SnowflakesConfig $config,
    ResolvesSequences $sequence,
)
```

--------------------------------

### firstForTimestamp()

Source: https://github.com/glhd/bits

Generates the smallest Snowflake ID at the given timestamp with datacenter_id, worker_id, and sequence all set to 0.

```APIDOC
## firstForTimestamp()

### Description
Generates the smallest Snowflake ID at the given timestamp with datacenter_id, worker_id, and sequence all set to 0.

### Method
firstForTimestamp(CarbonInterface $timestamp)

### Parameters
- **$timestamp** (CarbonInterface) - Required - The timestamp for the snowflake

### Return Type
Snowflake

### Example
```php
$since = $factory->firstForTimestamp(now()->subHour());
```
```

--------------------------------

### GenericFactory constructor

Source: https://github.com/glhd/bits

Constructor accepting epoch, worker IDs, configuration, and sequence resolver. validateConfiguration() calls $this->config->validate($this->ids).

```php
public function __construct(
    CarbonInterface $epoch,
    public readonly WorkerIds $ids,
    Configuration $config,
    ResolvesSequences $sequence,
)
```

--------------------------------

### new SnowflakeFactory()

Source: https://github.com/glhd/bits

Creates a new SnowflakeFactory instance with the given epoch, datacenter ID, worker ID, configuration, and sequence resolver.

```APIDOC
## Constructor

### Description
Creates a new SnowflakeFactory instance.

### Parameters
- **$epoch** (CarbonInterface) - Required - Epoch
- **$datacenter_id** (int) - Required - 0–31
- **$worker_id** (int) - Required - 0–31
- **$config** (SnowflakesConfig) - Required - Snowflake layout
- **$sequence** (ResolvesSequences) - Required - Sequence source

### Example
```php
use Glhd\Bits\Factories\SnowflakeFactory;
use Glhd\Bits\SequenceResolvers\InMemorySequenceResolver;

$factory = new SnowflakeFactory(
    epoch: now()->startOfDay(),
    datacenter_id: 3,
    worker_id: 15,
    config: app(SnowflakesConfig::class),
    sequence: new InMemorySequenceResolver(),
);
```
```

--------------------------------

### GenericConfig::combine

Source: https://github.com/glhd/bits

ORs each value into its segment's bit position to produce the combined 64-bit ID.

```APIDOC
## GenericConfig::combine

### Description
ORs each value into its segment's bit position to produce the combined 64-bit ID.

### Method
combine

### Signature
```php
public function combine(int ...$values): int
```

### Parameters
- **$values** (int) - Required - Values to combine into the ID

### Returns
- **int** - The combined 64-bit ID
```

--------------------------------

### Inherited Methods from Bits

Source: https://github.com/glhd/bits

All methods from the Bits base class apply to Sonyflake, including is(), toDateTime(), toCarbon(), __toString(), jsonSerialize(), and getValue(). These provide equality checking, timestamp recovery, string conversion, and query builder support.

```APIDOC
## Inherited Methods from Bits

### Description
All methods from `Bits` apply to Sonyflake instances.

### Methods

#### is(Bits $other): bool
- **Description**: Returns true only if the other object is also a `Sonyflake` with the same id (a `Snowflake` with the same numeric value is not equal).

#### toDateTime(): DateTimeInterface / toCarbon(): CarbonInterface
- **Description**: Recover the timestamp. The config's `unit = 10` means the timestamp value is multiplied by 10 ms when converting back.

#### __toString(): string / jsonSerialize(): mixed
- **Description**: String form for JavaScript-safe output.

#### getValue(?Grammar $grammar = null): int
- **Description**: `Expression` support for the query builder.

### Example: timestamp extraction
```php
use Glhd\Bits\Sonyflake;

$sonyflake = Sonyflake::fromId(56705782302306333);

$sonyflake->toCarbon()->format('Y-m-d H:i:s.u');
// 10ms-precision, so microseconds are rounded to the nearest 10ms
```
```

--------------------------------

### snowflake()

Source: https://github.com/glhd/bits

Global helper function. With no argument, returns the MakesSnowflakes factory from the container; with a value, returns the coerced Snowflake.

```APIDOC
## snowflake()

### Description
Global helper function. With no argument, returns the MakesSnowflakes factory from the container; with a value, returns the coerced Snowflake.

### Signature
`function snowflake(null|int|string|Bits $value = null): Snowflake|MakesSnowflakes`

### Parameters
- **$value** (null|int|string|Bits) - Optional - The value to coerce into a Snowflake. If null, returns the factory.

### Returns
- `Snowflake|MakesSnowflakes` - A Snowflake instance if a value is provided, otherwise the MakesSnowflakes factory.

### Example
```php
$factory   = snowflake();            // MakesSnowflakes
$new_id    = snowflake()->make();    // Snowflake
$parsed    = snowflake(65898467809951744); // Snowflake
```

```

--------------------------------

### GenericConfig::unitInMicroseconds()

Source: https://github.com/glhd/bits

Returns ceil(1000000 * (unit / 10^precision)) — the length of one timestamp tick in microseconds. Used by BitsFactory to decide how long to sleep when a sequence is exhausted (1,000 µs for snowflakes, 10,000 µs for sonyflakes).

```php
public function unitInMicroseconds(): int
```

--------------------------------

### Snowflake::make() method signature

Source: https://github.com/glhd/bits

Static factory method that creates a new Snowflake for the current moment via app(MakesSnowflakes::class)->make(). The factory reads worker and datacenter IDs from the 'bits' config.

```php
public static function make(): static
```

--------------------------------

### sonyflake() helper signature

Source: https://github.com/glhd/bits

Signature of the sonyflake() helper, the Sonyflake counterpart to snowflake().

```php
function sonyflake(null|int|string|Bits $value = null): Sonyflake|MakesSonyflakes
```

--------------------------------

### GenericConfig::maxSequence()

Source: https://github.com/glhd/bits

Returns the max value of the sequence segment (2^length - 1). 4095 for snowflakes, 255 for sonyflakes.

```php
public function maxSequence(): int
```
Tokens:
Raw