Initial commit

.github/workflows/style.yml

@@ -0,0 +1,29 @@
+name: styling
+
+on: [push]
+
+jobs:
+  style:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Run PHP CS Fixer
+        uses: docker://oskarstark/php-cs-fixer-ga
+        with:
+          args: --config=tools/.php-cs-fixer.php --allow-risky=yes
+
+      - name: Extract branch name
+        shell: bash
+        run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"
+        id: extract_branch
+
+      - name: Commit changes
+        uses: stefanzweifel/[email protected]
+        with:
+          commit_message: Fix styling
+          branch: ${{ steps.extract_branch.outputs.branch }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/tests.yml

@@ -0,0 +1,43 @@
+name: tests
+
+on: [push, pull_request]
+
+jobs:
+    phpunit:
+        runs-on: ${{ matrix.os }}
+        strategy:
+            fail-fast: false
+            matrix:
+                os: [ubuntu-latest]
+                php: [8.1]
+                laravel: [8.*]
+                dependency-version: [prefer-stable]
+                include:
+                    -   laravel: 8.*
+                        testbench: 6.*
+
+        name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.dependency-version }}
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v2
+
+            -   name: Install SQLite
+                run: |
+                    sudo apt-get update
+                    sudo apt-get install sqlite3
+
+            -   name: Setup PHP
+                uses: shivammathur/setup-php@v2
+                with:
+                    php-version: ${{ matrix.php }}
+                    extensions: curl, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, iconv
+                    coverage: none
+
+            -   name: Install dependencies
+                run: |
+                    composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
+                    composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction
+
+            -   name: Execute tests
+                run: vendor/bin/phpunit

.gitignore

@@ -0,0 +1,10 @@
+build
+composer.lock
+vendor
+storage
+tests/World/database.sqlite
+.DS_Store
+coverage
+.phpunit.result.cache
+.idea
+.php_cs.cache

LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © Matt Kingshott and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,126 @@
+<!-- Screenshot -->
+<p align="center">
+    <img src="resources/wallpaper.jpg" alt="Wallpaper">
+</p>
+
+<!-- Badges -->
+<p align="center">
+  <img src="resources/version.svg" alt="Version">
+  <img src="resources/license.svg" alt="License">
+</p>
+
+# Snowflake
+
+This package enables a Laravel application to create Twitter Snowflake identifiers. It is a very thin wrapper around the excellent [Snowflake PHP](https://github.com/godruoyi/php-snowflake) 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](https://itnext.io/choosing-the-right-data-type-means-of-generating-unique-primary-keys-d7aac92968c6) 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:
+
+```bash
+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:
+
+```bash
+php artisan vendor:publish
+```
+
+## Usage
+
+You can generate a Snowflake by resolving the service out of the container and calling its `id` method:
+
+```php
+resolve('snowflake')->id(); // (string) "5585066784854016"
+```
+
+Since this is a little cumbersome, the package also registers a global `snowflake()` helper method that you can use anywhere. This helper also converts the Snowflake from a `string` into an `integer`, which better reflects its data type:
+
+```php
+snowflake(); // (int) 5585066784854016
+```
+
+### 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.
+
+```php
+// Before
+$table->id();
+
+// After
+$table->unsignedBigInteger('id')->primary();
+```
+
+Here's an example:
+
+```php
+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
+<?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](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=YBEHLHPF3GUVY&source=url). Thanks so much!
+
+## License
+
+The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

composer.json

@@ -0,0 +1,45 @@
+{
+    "name": "mattkingshott/snowflake",
+    "description": "A package to create Twitter Snowflake identifiers",
+    "keywords": [
+        "snowflake",
+        "php",
+        "laravel",
+        "database"
+    ],
+    "type": "library",
+    "license": "MIT",
+    "homepage": "https://github.com/mattkingshott/snowflake",
+    "autoload": {
+        "psr-4": {
+            "Snowflake\\": "src"
+        },
+        "files": [
+            "src/Helpers.php"
+        ]
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Snowflake\\Tests\\": "tests"
+        }
+    },
+    "require": {
+        "php": "^8.0",
+        "godruoyi/php-snowflake": "^2.0"
+    },
+    "require-dev": {
+        "orchestra/testbench": "^6.0",
+        "phpunit/phpunit": "^9.0"
+    },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "Snowflake\\ServiceProvider"
+            ]
+        }
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit"
+    },
+    "minimum-stability": "stable"
+}

config/snowflake.php

@@ -0,0 +1,57 @@
+<?php declare(strict_types = 1);
+
+use Godruoyi\Snowflake\RandomSequenceResolver;
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Data Center
+    |--------------------------------------------------------------------------
+    |
+    | This value represents the data center reference that should be used by
+    | Snowflake when generating unique identifiers. The value must be 1 - 31.
+    |
+    */
+
+    'data_center' => 1,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Worker Node
+    |--------------------------------------------------------------------------
+    |
+    | This value represents the worker node reference that should be used by
+    | Snowflake when generating unique identifiers. The value must be 1 - 31.
+    |
+    */
+
+    'worker_node' => 1,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Start Timestamp
+    |--------------------------------------------------------------------------
+    |
+    | This value represents the starting date for generating new timestamps.
+    | Snowflakes can be created for 69 years past this date. In most cases,
+    | you should set this value to the current date when building a new app.
+    |
+    */
+
+    'start_timestamp' => '2022-01-01',
+
+    /*
+    |--------------------------------------------------------------------------
+    | Sequence Resolver
+    |--------------------------------------------------------------------------
+    |
+    | This value represents the sequencing strategy that should be used to
+    | ensure that multiple Snowflakes generated within the same millisecond
+    | are unique. The default is a good choice, as it has no dependencies.
+    |
+    */
+
+    'sequence_resolver' => RandomSequenceResolver::class,
+
+];

phpunit.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="vendor/autoload.php" backupGlobals="false" backupStaticAttributes="false" colors="true" verbose="true" convertErrorsToExceptions="true" convertNoticesToExceptions="true" convertWarningsToExceptions="true" processIsolation="false" stopOnFailure="false" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+  <coverage>
+    <include>
+      <directory suffix=".php">src/</directory>
+    </include>
+  </coverage>
+  <testsuites>
+    <testsuite name="Test Suite">
+      <directory>tests</directory>
+    </testsuite>
+  </testsuites>
+  <php>
+    <env name="APP_NAME" value="waterfall"/>
+  </php>
+</phpunit>