Laravel Snowflake

https://github.com/kra8/laravel-snowflake
Admin
Laravel Snowflake is a Laravel and Lumen package that generates 64-bit distributed identifiers...
Tokens:18,465
Snippets:142
Trust Score:7.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and publish for Laravel

Source: https://github.com/kra8/laravel-snowflake/blob/main/README.md

Install the package and publish its configuration for Laravel. Run these commands in your project root.

```bash
composer require "kra8/laravel-snowflake"

php artisan vendor:publish --provider="Kra8\Snowflake\Providers\LaravelServiceProvider"
```

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

### Install for Lumen

Source: https://github.com/kra8/laravel-snowflake/blob/main/README.md

Install the package via Composer for Lumen.

```bash
composer require "kra8/laravel-snowflake"
```

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

### Config with explicit epoch

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Example configuration with an explicit epoch, showing how the singleton is resolved with a converted timestamp.

```php
// config/snowflake.php (published by LaravelServiceProvider)
return [
    'epoch'         => '2019-04-01 00:00:00',
    'worker_id'     => 4,
    'datacenter_id' => 2,
];

// resolved singleton ≈
// new Snowflake(strtotime('2019-04-01 00:00:00'), 4, 2)
```

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

### Creating a record with shortflake ID

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasShortflakePrimary.md

Example of creating a record and retrieving the generated key.

```php
$user = User::create(['name' => 'Grace', 'email' => 'grace@example.com', 'password' => '…']);
$key = $user->getKey();

// Safe to hand to JavaScript clients:
echo $key; // 53-bit integer, e.g. 2101063680000123 (< 2^53)
```

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

### Config without epoch key

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Example configuration without an epoch key, relying on the class default epoch datetime.

```php
// config/snowflake.php — no 'epoch' key
return [
    'worker_id'     => 4,
    'datacenter_id' => 2,
];

// resolved singleton ≈
// new Snowflake(null, 4, 2)
// → constructor uses DEFAULT_EPOCH_DATETIME = '2021-02-02 00:00:00'
```

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

### Get Snowflake instance with app helper

Source: https://github.com/kra8/laravel-snowflake/blob/main/README.md

Get a Snowflake instance using the app helper function.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
```

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

### toShortflakeId() usage example

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Creates a Snowflake instance, calculates elapsed milliseconds since epoch, and calls toShortflakeId to generate a shortflake ID.

```php
$snowflake = new Snowflake();
$elapsed = $snowflake->timestamp() - $snowflake->epoch; // ms since epoch
$id = $snowflake->toShortflakeId($elapsed, 5);
```

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

### parse() inspecting generation time example

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Parses a newly generated snowflake ID and prints the binary representation, binary length, and generation datetime.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$parts = $snowflake->parse($snowflake->next());

echo $parts['binary'];        // e.g. "1111000101011..."
echo $parts['binary_length']; // total binary digits
echo $parts['datetime'];      // 'Y-m-d H:i:s' of generation
```

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

### parse() basic usage example

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Generates a snowflake ID with next() and parses it to extract worker_id, datacenter_id, and sequence fields.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->next();
$parts = $snowflake->parse($id);

$worker = $parts['worker_id'];       // 1
$datacenter = $parts['datacenter_id']; // 1
$seq = $parts['sequence'];
```

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

### Get Snowflake instance with make

Source: https://github.com/kra8/laravel-snowflake/blob/main/README.md

Get a Snowflake instance using the app container's make method.

```php
$snowflake = $this->app->make('Kra8\Snowflake\Snowflake');
```

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

### timestamp() usage example

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Retrieves the Snowflake instance from the container and calls timestamp() to get the current time in milliseconds, e.g., 1718640000123.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$nowMs = $snowflake->timestamp(); // e.g. 1718640000123
```

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

### toSnowflakeId() usage example

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Creates a Snowflake instance and calls toSnowflakeId with a timestamp and sequence to rebuild the same ID layout used internally by id(). Useful for tests.

```php
$snowflake = new Snowflake();
// Rebuilds the same id layout used internally by id(); mostly useful for tests
$id = $snowflake->toSnowflakeId(1554076800000, 7);
```

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

### Example: parse a snowflake id

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/types.md

Example usage of Snowflake::parse() with a new id from next(). Shows the expected types and ranges for the returned fields: timestamp is an int in milliseconds since epoch, worker_id and datacenter_id are ints 0-31, sequence is an int 0-4095, and datetime is a string formatted 'Y-m-d H:i:s'.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$parts = $snowflake->parse($snowflake->next());

$parts['timestamp'];      // int, ms since epoch
$parts['worker_id'];      // int, 0-31
$parts['datacenter_id'];  // int, 0-31
$parts['sequence'];       // int, 0-4095
$parts['datetime'];       // string 'Y-m-d H:i:s'
```

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

### Migration with a snowflake-compatible key column

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasSnowflakePrimary.md

Migration example using `$table->id()` which creates a bigint unsigned auto-increment column; the trait overrides auto-incrementing behavior.

```php
/**
 * Run the migrations.
 *
 * @return void
 */
public function up()
{
    Schema::create('users', function (Blueprint $table) {
        $table->id();
        $table->string('name');
        $table->string('email')->unique();
        $table->string('password');
        $table->rememberToken();
        $table->timestamps();
    });
}
```

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

### Usage inside a Lumen route handler

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LumenServiceProvider.md

Example of using the Snowflake singleton in a route handler to generate a new ID. The route returns an array with the 'id' key.

```php
// routes/web.php
$router->get('/next-id', function () {
    $snowflake = app('Kra8\Snowflake\Snowflake');
    return ['id' => $snowflake->next()];
});
```

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

### Model using the shortflake trait

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasShortflakePrimary.md

Example model class that uses HasShortflakePrimary and Notifiable.

```php
<?php
namespace App;

use Kra8\Snowflake\HasShortflakePrimary;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasShortflakePrimary, Notifiable;
}
```

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

### Override config before resolution

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LaravelServiceProvider.md

Sets the snowflake config values before resolving the generator, useful for tests or deploy-time setup.

```php
config()->set('snowflake', [
    'epoch'         => '2019-04-01 00:00:00',
    'worker_id'     => 1,
    'datacenter_id' => 1,
]);

$snowflake = app('Kra8\Snowflake\Snowflake');
```

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

### Eloquent model using HasSnowflakePrimary (README pattern)

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasSnowflakePrimary.md

Example Eloquent model that uses the trait. The trait automatically sets `$incrementing` to false. Requires the provider to be registered for `app(Snowflake::class)` resolution.

```php
<?php
namespace App;

use Kra8\Snowflake\HasSnowflakePrimary;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasSnowflakePrimary, Notifiable;
}
```

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

### Generate a sequence ID with makeSequenceId()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Generates a sequence value for the current millisecond, either incrementing the previous sequence or re-seeding with a random value. The example creates a new Snowflake instance and calls makeSequenceId() with the current timestamp.

```php
$snowflake = new Snowflake();
$seq = $snowflake->makeSequenceId($snowflake->timestamp());
// $seq is 0..4095 (or higher if the sequence counter overflows within one millisecond)
```

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

### boot() method signature

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LumenServiceProvider.md

Public boot method with no parameters. Returns void per docblock and throws no exceptions.

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

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

### boot()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Abstract method that must be implemented by subclasses to handle framework-specific bootstrap, such as publishing or merging the snowflake config file.

```APIDOC
## boot()

### Description
Abstract method that must be implemented by subclasses to handle framework-specific bootstrap, such as publishing or merging the snowflake config file.

### Method
boot

### Signature
```php
abstract public function boot();
```

### Parameters
None

### Return Type
void

### Throws
None defined; each subclass implementation decides the config publication strategy.

### Behavior
Abstract — every subclass must implement the framework-specific bootstrap (publish or merge `config/snowflake.php`).

### Source
`src/Providers/AbstractServiceProvider.php:15-19`
```

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

### Publish config file in boot()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LaravelServiceProvider.md

Publishes the package's config/snowflake.php to the application's config path.

```php
$this->publishes([
    __DIR__ . '/../../config/snowflake.php' => config_path('snowflake.php'),
]);
```

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

### boot() method implementation merging config

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LumenServiceProvider.md

Resolves the package's config file and merges it into the application config under the 'snowflake' key using mergeConfigFrom. This loads config/snowflake.php and merges its epoch, worker_id, and datacenter_id keys.

```php
$path = realpath(__DIR__.'/../../config/snowflake.php');

$this->mergeConfigFrom($path, 'snowflake');
```

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

### Publish configuration

Source: https://github.com/kra8/laravel-snowflake/blob/main/README.md

Publish the configuration file if config/snowflake.php does not exist.

```bash
php artisan vendor:publish
```

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

### Abstract boot method declaration

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Abstract boot method that every subclass must implement to handle framework-specific configuration publishing or merging.

```php
abstract public function boot();
```

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

### bootHasShortflakePrimary method signature

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasShortflakePrimary.md

Signature of the boot method that registers the saving event.

```php
public static function bootHasShortflakePrimary()
```

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

### Boot method signature: `bootHasSnowflakePrimary()`

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasSnowflakePrimary.md

Method signature for the Eloquent boot hook. Returns `void`. Registers the package-style `static::saving` event hook. Errors may surface from the event system or container resolution of `Snowflake`.

```php
public static function bootHasSnowflakePrimary()
```

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

### Snowflake constructor - Direct instantiation parameters

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/configuration.md

Constructor signature for direct instantiation of the Snowflake class outside the container. Accepts an optional epoch timestamp in Unix seconds (null defaults to '2021-02-02 00:00:00'), a worker ID (5 bits), and a datacenter ID (5 bits). The timestamp is internally stored as milliseconds.

```php
public function __construct(?int $timestamp = null, int $workerId = 1, int $datacenterId = 1)
```

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

### config/snowflake.php - Package configuration file

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/configuration.md

The package's only configuration file, shipped with the package and published to the host application. It defines three keys: 'epoch', 'worker_id', and 'datacenter_id', each with an environment variable fallback. The epoch default is '2019-04-01 00:00:00', while worker and datacenter IDs default to 1.

```php
<?php
return [
    'epoch' => env('SNOWFLAKE_EPOCH', '2019-04-01 00:00:00'),
    'worker_id' => env('SNOWFLAKE_WORKER_ID', 1),
    'datacenter_id' => env('SNOWFLAKE_DATACENTER_ID', 1),
];
```

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

### Default instantiation and ID generation

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Creates a Snowflake instance with default epoch, worker ID 1, and datacenter ID 1, then generates an ID using next().

```php
use Kra8\Snowflake\Snowflake;

$snowflake = new Snowflake(); // default epoch, worker_id = 1, datacenter_id = 1
$id = $snowflake->next();
```

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

### Verifying merged config took effect

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LumenServiceProvider.md

Shows how to parse a generated ID to inspect worker_id and datacenter_id fields, which mirror the merged config values.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');

// The singleton was built from snowflake.worker_id / snowflake.datacenter_id.
// Parse a generated id to inspect those fields:
$parts = $snowflake->parse($snowflake->next());
echo $parts['worker_id'];      // mirrors config 'snowflake.worker_id'
echo $parts['datacenter_id'];  // mirrors config 'snowflake.datacenter_id'
```

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

### register()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Registers the Snowflake class as a container singleton, resolving it from the snowflake.* configuration keys with defaults for epoch, worker_id, and datacenter_id.

```APIDOC
## register()

### Description
Registers the Snowflake class as a container singleton, resolving it from the snowflake.* configuration keys with defaults for epoch, worker_id, and datacenter_id.

### Method
register

### Signature
```php
public function register()
```

### Parameters
None

### Return Type
None (the method's side effect is the container registration)

### Throws
None

### Behavior
Registers `Snowflake::class` as a container singleton:

```php
$this->app->singleton(Snowflake::class, function () {
    $epoch = config('snowflake.epoch', null);
    $workerId = config('snowflake.worker_id', 1);
    $datacenterId = config('snowflake.datacenter_id', 1);
    $timestamp = $epoch === null ? null :  $timestamp = strtotime($epoch);
    return new Snowflake($timestamp, $workerId, $datacenterId);
});
```

### Resolution Rules
- `snowflake.epoch` — read with default `null`. When `null` (key absent), the resolver passes `null` to the [Snowflake constructor](Snowflake.md), which falls back to `DEFAULT_EPOCH_DATETIME = '2021-02-02 00:00:00'`. When set, it is assumed to be a `'Y-m-d H:i:s'` string and converted via `strtotime()`.
- `snowflake.worker_id` — default `1`.
- `snowflake.datacenter_id` — default `1`.

The instance is a **singleton**: one `Snowflake` instance per container, so the per-instance sequence counter guarantees ordering/uniqueness within the application process.

### Source
`src/Providers/AbstractServiceProvider.php:22-31`

### Example — resolution behavior with an explicit epoch config

```php
// config/snowflake.php (published by LaravelServiceProvider)
return [
    'epoch'         => '2019-04-01 00:00:00',
    'worker_id'     => 4,
    'datacenter_id' => 2,
];

// resolved singleton ≈
// new Snowflake(strtotime('2019-04-01 00:00:00'), 4, 2)
```

### Example — with the epoch key unset, relying on the class default

```php
// config/snowflake.php — no 'epoch' key
return [
    'worker_id'     => 4,
    'datacenter_id' => 2,
];

// resolved singleton ≈
// new Snowflake(null, 4, 2)
// → constructor uses DEFAULT_EPOCH_DATETIME = '2021-02-02 00:00:00'
```
```

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

### Resolving Snowflake from container

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Shows how to resolve the Snowflake singleton from the container and generate an ID with next().

```php
$snowflake = $this->app->make('Kra8\Snowflake\Snowflake');
// or
$snowflake = app('Kra8\Snowflake\Snowflake');

$id = $snowflake->next();
```

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

### Direct instantiation with explicit epoch

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Creates a Snowflake instance with a custom epoch (2019-04-01 00:00:00 UTC), worker 3, and datacenter 2.

```php
use Kra8\Snowflake\Snowflake;

// Epoch 2019-04-01 00:00:00 UTC, worker 3, datacenter 2
$snowflake = new Snowflake(1554076800, 3, 2);
```

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

### Singleton registration for Snowflake

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Registers Snowflake as a singleton, reading configuration keys snowflake.epoch, snowflake.worker_id, and snowflake.datacenter_id. When epoch is null, null is passed to the constructor, which falls back to DEFAULT_EPOCH_DATETIME. The singleton ensures per-instance sequence counter ordering.

```php
$this->app->singleton(Snowflake::class, function () {
    $epoch = config('snowflake.epoch', null);
    $workerId = config('snowflake.worker_id', 1);
    $datacenterId = config('snowflake.datacenter_id', 1);
    $timestamp = $epoch === null ? null :  $timestamp = strtotime($epoch);
    return new Snowflake($timestamp, $workerId, $datacenterId);
});
```

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

### Imports for AbstractServiceProvider

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Imports the base ServiceProvider and the Snowflake class used by the provider.

```php
use Illuminate\Support\ServiceProvider;
use Kra8\Snowflake\Snowflake;
```

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

### Snowflake config array from config/snowflake.php

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/types.md

Configuration array served by config/snowflake.php. The epoch key is a date string in 'Y-m-d H:i:s' format, consumed via strtotime(); worker_id and datacenter_id are ints passed directly to the Snowflake constructor. Defaults come from environment variables SNOWFLAKE_EPOCH, SNOWFLAKE_WORKER_ID, and SNOWFLAKE_DATACENTER_ID.

```php
return [
    'epoch' => env('SNOWFLAKE_EPOCH', '2019-04-01 00:00:00'),
    'worker_id' => env('SNOWFLAKE_WORKER_ID', 1),
    'datacenter_id' => env('SNOWFLAKE_DATACENTER_ID', 1),
];
```

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

### Snowflake::__construct

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Constructor for the Snowflake class, allowing configuration of epoch, worker ID, and datacenter ID.

```APIDOC
## Constructor

### Description
Creates a new Snowflake instance with an optional epoch timestamp, worker ID, and datacenter ID.

### Method
Constructor

### Signature
`public function __construct(?int $timestamp = null, int $workerId = 1, int $datacenterId = 1)`

### Parameters
- **$timestamp** (?int) - Optional - Unix epoch seconds. When null, defaults to '2021-02-02 00:00:00'.
- **$workerId** (int) - Optional - Worker ID, occupies 5 bits in the snowflake layout. Default: 1.
- **$datacenterId** (int) - Optional - Datacenter ID, occupies 5 bits in the snowflake layout. Default: 1.

### Return Type
`Snowflake` instance

### Throws
None

### Example
```php
use Kra8\Snowflake\Snowflake;

// Epoch 2019-04-01 00:00:00 UTC, worker 3, datacenter 2
$snowflake = new Snowflake(1554076800, 3, 2);
```
```

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

### Manual registration in bootstrap/app.php

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LumenServiceProvider.md

Lumen requires manual registration of the provider in the bootstrap file. Place this inside the providers section of bootstrap/app.php.

```php
// bootstrap/app.php — inside the providers section
$app->register(Kra8\Snowflake\Providers\LumenServiceProvider::class);
```

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

### next()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Generates a unique 64-bit snowflake ID by delegating to id(). Returns an integer.

```APIDOC
## next()

### Description
Returns a unique 64-bit snowflake id by delegating to `id()`. Uniqueness is guaranteed per instance under normal conditions, but across services requires distinct worker and datacenter IDs.

### Method
PHP method

### Endpoint
`public function next(): int`

### Parameters
None.

### Return Type
- **int** — a unique 64-bit snowflake id.

### Throws
None. Under heavy per-millisecond load, the method blocks (see `id()`) rather than raising.

### Behavior
Exactly delegates to `id()` (`return $this->id();`). Uniqueness is enforced per instance via `$sequence`/`$lastTimestamp`.

### Example
```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->next(); // e.g. 6723854613151887360
```
```

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

### Creating a record with automatic snowflake key

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasSnowflakePrimary.md

After the model and migration are set up, creating a record assigns a snowflake key transparently. The `getKey()` returns a 64-bit snowflake id, e.g., 6723854613151887360.

```php
$user = User::create(['name' => 'Ada', 'email' => 'ada@example.com', 'password' => '…']);
echo $user->getKey(); // 64-bit snowflake id, e.g. 6723854613151887360
```

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

### toShortflakeId() method signature

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Declares the public method toShortflakeId that packs a timestamp and sequence into a 53-bit shortflake ID.

```php
public function toShortflakeId(int $currentTime, int $sequenceId)
```

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

### register method signature

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Registers the Snowflake class as a container singleton. The method signature is shown without a return type.

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

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

### Import Snowflake class

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasShortflakePrimary.md

Imports the Snowflake class used by the trait.

```php
use Kra8\Snowflake\Snowflake;
```

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

### Register Lumen service provider

Source: https://github.com/kra8/laravel-snowflake/blob/main/README.md

Register the Lumen service provider in the bootstrap/app.php file under the providers section.

```php
// Add this line
$app->register(Kra8\Snowflake\Providers\LumenServiceProvider::class);
```

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

### toSnowflakeId() method signature

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Declares the public method toSnowflakeId that packs a timestamp and sequence into a 64-bit snowflake ID.

```php
public function toSnowflakeId(int $currentTime, int $sequenceId)
```

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

### Class declaration for LumenServiceProvider

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LumenServiceProvider.md

Declares the LumenServiceProvider class extending AbstractServiceProvider. The class body has no use statements and no constructor.

```php
class LumenServiceProvider extends AbstractServiceProvider
```

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

### Snowflake::parse() result array

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/types.md

Return value of Snowflake::parse() with exactly 12 keys: binary_length, binary, binary_timestamp, binary_sequence, binary_worker_id, binary_datacenter_id, timestamp, sequence, worker_id, datacenter_id, epoch, and datetime. The binary_* fields are string slices of the binary id; timestamp/sequence/worker_id/datacenter_id are bindec() conversions; epoch is the instance epoch in milliseconds; datetime is the generation wall-clock time formatted 'Y-m-d H:i:s'.

```php
return [
    'binary_length' => strlen($id),
    'binary' => $id,
    'binary_timestamp' => $binaryTimestamp,
    'binary_sequence' => $binarySequence,
    'binary_worker_id' => $binaryWorkerId,
    'binary_datacenter_id' => $binaryDatacenterId,
    'timestamp' => $timestamp,
    'sequence' => bindec($binarySequence),
    'worker_id' => bindec($binaryWorkerId),
    'datacenter_id' => bindec($binaryDatacenterId),
    'epoch' => $this->epoch,
    'datetime' => $datetime,
];
```

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

### Generate snowflake ID with next()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Retrieves the Snowflake service from the Laravel container and generates a unique 64-bit snowflake ID using the next() method. The method delegates to id() and blocks under heavy load rather than throwing.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->next(); // e.g. 6723854613151887360
```

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

### short()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Generates a 53-bit Snowflake ID that is safe for JavaScript number handling. It uses the same millisecond-loop as id() but omits worker and datacenter bits.

```APIDOC
## short()

### Description
Generates a 53-bit Snowflake ID (timestamp_bits(41) + sequence_bits(12)) that is safe for JavaScript number handling. It uses the same millisecond-loop as id() but omits worker and datacenter bits.

### Method
short()

### Signature
```php
public function short(): int
```

### Parameters
None.

### Return Type
- `int` — a 53-bit id (`timestamp_bits(41) + sequence_bits(12)`), safe for JavaScript number handling.

### Throws
None; stalls via `usleep(1)` identically to `id()`.

### Behavior
Same millisecond-loop as `id()`, but builds the id with `toShortflakeId($currentTime - $this->epoch, $sequenceId)` — no worker/datacenter bits are placed in the result. Shared per-instance state (`$lastTimestamp`, `$sequence`) means `short()` and `id()`/`next()` on the same instance cannot collide per millisecond.

### Example
```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->short(); // fits in a 53-bit JavaScript-safe integer
```
```

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

### toShortflakeId(int $currentTime, int $sequenceId)

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Packs the given current time and sequence ID into a 53-bit shortflake value. This method is useful for generating short IDs without worker or datacenter bits.

```APIDOC
## toShortflakeId(int $currentTime, int $sequenceId)

### Description
Packs the given current time and sequence ID into a 53-bit shortflake value. This method is useful for generating short IDs without worker or datacenter bits.

### Method
`toShortflakeId`

### Signature
`public function toShortflakeId(int $currentTime, int $sequenceId)`

### Parameters
- **$currentTime** (int) - Required - Milliseconds elapsed since epoch.
- **$sequenceId** (int) - Required - Sequence value.

### Return Type
- **int** - A 53-bit value: `($currentTime << SEQUENCE_BITS) | $sequenceId`. No worker/datacenter or sign bits are included.

### Throws
- None.

### Example
```php
$snowflake = new Snowflake();
$elapsed = $snowflake->timestamp() - $snowflake->epoch; // ms since epoch
$id = $snowflake->toShortflakeId($elapsed, 5);
```
```

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

### toSnowflakeId(int $currentTime, int $sequenceId)

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Packs the given current time and sequence ID into a 64-bit snowflake value. This method is useful for rebuilding the same ID layout used internally by `id()`, primarily for testing.

```APIDOC
## toSnowflakeId(int $currentTime, int $sequenceId)

### Description
Packs the given current time and sequence ID into a 64-bit snowflake value. This method is useful for rebuilding the same ID layout used internally by `id()`, primarily for testing.

### Method
`toSnowflakeId`

### Signature
`public function toSnowflakeId(int $currentTime, int $sequenceId)`

### Parameters
- **$currentTime** (int) - Required - Milliseconds elapsed since epoch (`currentTime - epoch`).
- **$sequenceId** (int) - Required - Sequence value, occupies the low 12 bits.

### Return Type
- **int** - The packed 64-bit snowflake value.

### Layout
- `workerIdLeftShift = SEQUENCE_BITS` (12)
- `datacenterIdLeftShift = WORKER_ID_BITS + SEQUENCE_BITS` (17)
- `timestampLeftShift = DATACENTER_ID_BITS + WORKER_ID_BITS + SEQUENCE_BITS` (22)
- result = `(currentTime << 22) | (datacenterId << 17) | (workerId << 12) | sequenceId`

### Example
```php
$snowflake = new Snowflake();
// Rebuilds the same id layout used internally by id(); mostly useful for tests
$id = $snowflake->toSnowflakeId(1554076800000, 7);
```
```

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

### parse() method signature

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Declares the public parse() method that accepts an integer snowflake ID and returns an associative array of its binary fields.

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

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

### timestamp()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Returns the current Unix time in milliseconds, computed as `(int) floor(microtime(true) * 1000)`. This method takes no parameters and returns an integer.

```APIDOC
## `timestamp()`

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

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| — | — | — | — | no parameters |

- **Return type**: `int` — current Unix time in milliseconds, computed as `(int) floor(microtime(true) * 1000)`.
- **Throws**: none.
- **Source**: `src/Snowflake.php:154-157`.

Example:

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$nowMs = $snowflake->timestamp(); // e.g. 1718640000123
```
```

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

### timestamp() method signature

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Declares the public timestamp() method that returns an integer representing the current Unix time in milliseconds.

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

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

### Register provider in composer.json

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LaravelServiceProvider.md

Adds the LaravelServiceProvider to Laravel's auto-discovery providers list.

```json
// composer.json
"extra": {
    "laravel": {
        "providers": [
            "Kra8\\Snowflake\\Providers\\LaravelServiceProvider"
        ]
    }
}
```

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

### Class declaration for LaravelServiceProvider

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LaravelServiceProvider.md

Declares the LaravelServiceProvider class extending AbstractServiceProvider.

```php
class LaravelServiceProvider extends AbstractServiceProvider
```

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

### Abstract class declaration for AbstractServiceProvider

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/AbstractServiceProvider.md

Declares the abstract base class for Laravel and Lumen service providers. It extends Illuminate\Support\ServiceProvider and is subclassed by LaravelServiceProvider and LumenServiceProvider.

```php
abstract class AbstractServiceProvider extends ServiceProvider
```

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

### Class declaration

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Declares the Snowflake class.

```php
class Snowflake
```

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

### Generate snowflake ID with id()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Retrieves the Snowflake service from the Laravel container and generates a 64-bit snowflake ID using the id() method. The method stalls via usleep(1) when the sequence is exhausted, and returns an ID identical in shape to next().

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->id(); // identical result shape to ->next()
```

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

### id()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Generates a 64-bit snowflake ID for the current millisecond, blocking if the sequence is exhausted.

```APIDOC
## id()

### Description
Generates a 64-bit snowflake id for the current millisecond. It blocks via `usleep(1)` when the sequence is exhausted, ensuring uniqueness within the same millisecond.

### Method
PHP method

### Endpoint
`public function id(): int`

### Parameters
None.

### Return Type
- **int** — the 64-bit snowflake id for the current millisecond.

### Throws
None; stalls via `usleep(1)` while the sequence is exhausted.

### Behavior
1. Reads `$currentTime = $this->timestamp()` (current Unix time in milliseconds).
2. Calls `makeSequenceId($currentTime)` in a loop; while the produced sequence exceeds `MAX_SEQUENCE` (4095), sleeps 1 microsecond and re-reads the timestamp.
3. Stores `$lastTimestamp = $currentTime` and returns `toSnowflakeId($currentTime - $this->epoch, $sequenceId)`.

### Example
```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->id(); // identical result shape to ->next()
```
```

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

### Generate a 53-bit JavaScript-safe ID with short()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Creates a short Snowflake ID that fits in a 53-bit integer, safe for JavaScript. Uses the application container to resolve the Snowflake instance. No parameters required.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->short(); // fits in a 53-bit JavaScript-safe integer
```

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

### Saving event hook implementation

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasShortflakePrimary.md

Registers the static::saving event to assign a shortflake ID when the model key is null.

```php
static::saving(function ($model) {
    if (is_null($model->getKey())) {
        $model->setIncrementing(false);
        $keyName    = $model->getKeyName();
        $id         = app(Snowflake::class)->short();
        $model->setAttribute($keyName, $id);
    }
});
```

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

### Resolve Snowflake generator in Laravel

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/LaravelServiceProvider.md

Resolves the Snowflake singleton from the container and generates IDs.

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->next();     // 64-bit snowflake id, config-driven epoch/worker/datacenter
$shortId = $snowflake->short(); // 53-bit JavaScript-safe id
```

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

### Saving event hook implementation

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasSnowflakePrimary.md

Registers a `static::saving` listener that assigns a snowflake id only when `$model->getKey()` is null. It disables auto-increment, reads the key column name, generates an id via `app(Snowflake::class)->next()`, and sets the attribute. Existing records are left untouched.

```php
static::saving(function ($model) {
    if (is_null($model->getKey())) {
        $model->setIncrementing(false);
        $keyName    = $model->getKeyName();
        $id         = app(Snowflake::class)->next();
        $model->setAttribute($keyName, $id);
    }
});
```

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

### parse(int $id)

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Parses a snowflake ID into its constituent fields (timestamp, sequence, worker_id, datacenter_id, and derived datetime). Accepts an integer ID and returns an associative array.

```APIDOC
## `parse()`

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

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$id` | `int` | yes | — | A snowflake id previously generated by this instance (needed for `epoch`-relative fields). |

- **Return type**: `array` — an associative array decomposing the id into its binary fields; see [types.md](../types.md) for the exact key set and the `datetime` derivation.
- **Throws**: none.
- **Behavior** (`src/Snowflake.php:159-185`): converts the id to a binary string with `decbin($id)`, then slices:
  - `timestamp` from the high bits (everything before the trailing 22 bits),
  - `sequence` from the low 12 bits,
  - `worker_id` from the 5 bits at shift 12,
  - `datacenter_id` from the 5 bits at shift 17,
  - and recomputes `datetime = date('Y-m-d H:i:s', (($timestamp + $this->epoch) / 1000) | 0)`.
- **Note**: the parse is not round-trip safe for negative ids, and `strlen($id)`/bit slicing assume a canonical binary string; for values produced by this instance's layout (all 63 payload bits positive) it matches the documented keys.

Example — basic:

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->next();
$parts = $snowflake->parse($id);

$worker = $parts['worker_id'];       // 1
$datacenter = $parts['datacenter_id']; // 1
$seq = $parts['sequence'];
```

Example — inspecting generation time:

```php
$snowflake = app('Kra8\Snowflake\Snowflake');
$parts = $snowflake->parse($snowflake->next());

echo $parts['binary'];        // e.g. "1111000101011..."
echo $parts['binary_length']; // total binary digits
echo $parts['datetime'];      // 'Y-m-d H:i:s' of generation
```
```

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

### Generate snowflake ID

Source: https://github.com/kra8/laravel-snowflake/blob/main/README.md

Generate a snowflake identifier by calling the next method on the Snowflake instance.

```php
$id = $snowflake->next();
```

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

### Trait declaration

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasShortflakePrimary.md

Declares the HasShortflakePrimary trait.

```php
trait HasShortflakePrimary
```

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

### Protected constants

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Defines the bit layout and timing constants for the snowflake ID. ID_BITS and TIMEOUT are declared but unused; MAX_SEQUENCE is 4095, the max value for 12 bits.

```php
protected const DEFAULT_EPOCH_DATETIME = '2021-02-02 00:00:00';
protected const ID_BITS = 63;
protected const TIMESTAMP_BITS = 41;
protected const WORKER_ID_BITS = 5;
protected const DATACENTER_ID_BITS = 5;
protected const SEQUENCE_BITS = 12;
protected const TIMEOUT = 1000;
protected const MAX_SEQUENCE = 4095;
```

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

### makeSequenceId()

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/Snowflake.md

Generates the sequence value for a Snowflake ID, handling millisecond collisions by incrementing the sequence or re-seeding with a random value.

```APIDOC
## makeSequenceId()

### Description
Generates the sequence value for a Snowflake ID, handling millisecond collisions by incrementing the sequence or re-seeding with a random value.

### Method
makeSequenceId()

### Signature
```php
public function makeSequenceId(int $currentTime, int $max = self::MAX_SEQUENCE): int
```

### Parameters
- `$currentTime` (int) - Required - Current timestamp in milliseconds, compared against `$lastTimestamp`.
- `$max` (int) - Optional - Default: `self::MAX_SEQUENCE` (4095) - Upper bound for the random re-seed.

### Return Type
- `int` — the sequence value for this call.

### Throws
None.

### Behavior
If `$lastTimestamp === $currentTime` (same millisecond as the previous call), increments `$this->sequence` by 1 and returns it. Otherwise re-seeds `$this->sequence = mt_rand(0, $max)`, records `$lastTimestamp = $currentTime`, and returns the new random sequence. This is the millisecond-collision guard; callers (`id()`, `short()`) loop while the returned value exceeds `MAX_SEQUENCE`.

### Example
```php
$snowflake = new Snowflake();
$seq = $snowflake->makeSequenceId($snowflake->timestamp());
// $seq is 0..4095 (or higher if the sequence counter overflows within one millisecond)
```
```

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

### Trait declaration: `trait HasSnowflakePrimary`

Source: https://github.com/kra8/laravel-snowflake/blob/main/_autodocs/api-reference/HasSnowflakePrimary.md

Declares the `HasSnowflakePrimary` trait. Note the dependency: `use Kra8\Snowflake\Snowflake;` is required for the trait to resolve the snowflake generator.

```php
trait HasSnowflakePrimary
```

```php
use Kra8\Snowflake\Snowflake;
```
Tokens:
Raw