Snowflake

This package enables a Laravel application to create Twitter Snowflake identifiers. It is a very thin wrapper around the excellent Snowflake PHP library created by Godruoyi.

What are Snowflakes?

Snowflakes are a form of unique identifier devised by Twitter. In this respect, they are similar to other unique identifier algorithms such as UUID or ULID.

Why should I use them?

I've written an article exploring the benefits of Snowflakes over other unique identifiers. However, in short:

• They consists entirely of integers.
• They uses less space (16 characters, so it fits in a BIGINT).
• Indexing of integers is much faster than indexing a string.
• Keys begin with a timestamp, so are sortable.
• Keys end with a random number, so guessing table size is not possible.
• Databases handle integers more efficiently than strings.
• Generation of new keys is faster (less than 1 ms).

Installation

Pull in the package using Composer:

composer require mattkingshott/snowflake

Configuration

Snowflake includes a configuration file that allows you to set:

1. The data center number.
2. The worker node number.
3. The starting timestamp.
4. The sequence resolver.

Most developers won't need to alter these values unless they need to set up a distributed architecture for generating Snowflakes.

If you want to change any of the values, publish the configuration file using Artisan:

php artisan vendor:publish

Usage

You can generate a Snowflake by resolving the service out of the container and calling its id method:

resolve('snowflake')->id(); // (string) "5585066784854016"

WARNING: Do not create instances of the Snowflake service, as doing so risks generating matching keys / introducing collisions. Instead, always resolve the Snowflake singleton out of the container. You can also use the global helper method (see below).

Since this is a little cumbersome, the package also registers a global snowflake() helper method that you can use anywhere.

snowflake(); // (string) "5585066784854016"

IMPORTANT: The initial release converted the Snowflake to an integer. This has been rolled back to prevent integer overflows in some languages.

Eloquent models

If you want to use a Snowflake as the primary key for an Eloquent model, then you'll need to perform a couple of steps.

First, modify the model's migration so that it no longer uses auto-incrementing integers e.g.

// Before
$table->id();

// After
$table->unsignedBigInteger('id')->primary();

Here's an example:

class CreateUsersTable extends Migration
{
    public function up()
    {
        Schema::create('users', function(Blueprint $table) {
            $table->unsignedBigInteger('id')->primary();
            $table->string('name', 100);
            $table->timestamps();
        });
    }
}

Finally, add the package's Snowflakes trait to the model:

<?php

namespace App\Models;

use Snowflake\Snowflakes;

class User extends Model
{
    use Snowflakes;
}

Contributing

Thank you for considering a contribution to Snowflake. You are welcome to submit a PR containing improvements, however if they are substantial in nature, please also be sure to include a test or tests.

Support the project

If you'd like to support the development of Snowflake, then please consider sponsoring me. Thanks so much!

License

The MIT License (MIT). Please see License File for more information.