Laravel Snowflake

To use snowflake identifiers as primary keys in your Eloquent models, use the Kra8\Snowflake\HasSnowflakePrimary trait. This trait automatically sets the $incrementing property to false and configures the model to use the snowflake type.

Ensure your database migration uses the id() column type (which maps to a 64-bit integer).

namespace App;

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

class User extends Authenticatable
{
    use HasSnowflakePrimary;
}

Standard 64-bit integers can cause precision issues in JavaScript. To generate a 53-bit integer that can be safely handled by JavaScript, use the Kra8\Snowflake\HasShortflakePrimary trait instead of HasSnowflakePrimary in your Eloquent model.

namespace App;

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

class User extends Authenticatable
{
    use HasShortflakePrimary;
}

To install the package in a Laravel project, use Composer to require the package and then publish the provider configuration.

composer require "kra8/laravel-snowflake"
php artisan vendor:publish --provider="Kra8\Snowflake\Providers\LaravelServiceProvider"

To install the package in a Lumen project, first install via Composer, then manually register the service provider in your bootstrap/app.php file.

composer require "kra8/laravel-snowflake"

// In bootstrap/app.php
$app->register(Kra8\Snowflake\Providers\LumenServiceProvider::class);

If the configuration file config/snowflake.php does not exist in your project, you can publish it using the Artisan command:

php artisan vendor:publish

To use Laravel Snowflake in a Lumen application, you must register the LumenServiceProvider. This ensures that the package configuration is correctly merged into the application container under the snowflake key.

$app->register(Kra8\Snowflake\Providers\LumenServiceProvider::class);

To customize the package settings, you can publish the snowflake.php configuration file to your application's config directory using the Laravel vendor:publish command. This allows you to manage Snowflake connection details and other package options within your own codebase.

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

You can resolve the Snowflake instance from the service container using the Kra8\Snowflake\Snowflake class and then call the next() method to generate a new 64-bit identifier.

$snowflake = app('Kra8\Snowflake\Snowflake');
$id = $snowflake->next();

If you require smaller identifiers, the short() method generates a 53-bit ID. This ID is composed only of the timestamp bits (41) and the sequence bits (12), omitting the datacenter and worker ID components.

use Kra8\Snowflake\Snowflake;

$snowflake = new Snowflake();
$shortId = $snowflake->short();

The next() method (and its alias id()) generates a unique 64-bit integer identifier based on the Snowflake algorithm. It incorporates a timestamp, datacenter ID, worker ID, and a sequence number to ensure uniqueness across distributed systems.

To use it, instantiate the Snowflake class with your specific workerId and datacenterId to prevent collisions between different nodes.

use Kra8\Snowflake\Snowflake;

// Initialize with custom worker and datacenter IDs
$snowflake = new Snowflake(null, 1, 1);

// Generate a 64-bit ID
$id = $snowflake->next();

The parse(int $id) method decomposes a 64-bit Snowflake ID back into its constituent parts. It returns an associative array containing the binary representations and the decoded integer values for the timestamp, sequence, worker ID, datacenter ID, and the human-readable datetime.

use Kra8\Snowflake\Snowflake;

$snowflake = new Snowflake();
$id = $snowflake->next();

$components = $snowflake->parse($id);

/*
$components will contain:
[
    'binary_length' => string,
    'binary' => string,
    'binary_timestamp' => string,
    'binary_sequence' => string,
    'binary_worker_id' => string,
    'binary_datacenter_id' => string,
    'timestamp' => int,
    'sequence' => int,
    'worker_id' => int,
    'datacenter_id' => int,
    'epoch' => int,
    'datetime' => string (Y-m-d H:i:s),
]
*/

The Snowflake constructor allows you to define the custom parameters for your ID generation environment:

• ?int $timestamp: The epoch time in seconds. If null, it defaults to 2021-02-02 00:00:00.
• int $workerId: A unique identifier for the current worker (default: 1).
• int $datacenterId: A unique identifier for the current datacenter (default: 1).

use Kra8\Snowflake\Snowflake;

// Custom epoch (as unix timestamp), worker ID 5, datacenter ID 2
$snowflake = new Snowflake(1612435200, 5, 2);