phossa2/uuid

A PHP lib to generate sequential/time based uuid for using as PK in DB.

phossa2/uuid

, _(*1)

phossa2/uuid is a PHP library for generating sequential UUID to be used as primary key in databases., _(*2)

It requires PHP 5.4, supports PHP 7.0+ and HHVM. It is compliant with PSR-1, PSR-2, PSR-3, PSR-4, and the proposed PSR-5., _(*3)

Installation

Install via the composer utility., _(*4)

composer require "phossa2/uuid"

or add the following lines to your composer.json, _(*5)

{
    "require": {
       "phossa2/uuid": "2.*"
    }
}

Features

• Ordered UUID, _(*6)

  According to article Store UUID in an optimized way, Non-ordered UUID has big impact on Mysql db insert performance., _(*7)

• Typed UUID, _(*8)

  Instead of following RFC 4122 for generating UUID, we adopted a new design with data types built in. For example, user id has the type of 1010. And any user id using this lib will start with '2101-0', _(*9)

• Sharding supported, _(*10)

  With sharding bits built-in, it is easy to shard your db tables., _(*11)

• Ready for extension, _(*12)

  As long as the timestamp algorithm is good enough, it will guarantee uniqueness at least inside one vendor's house., _(*13)

Design

Using 32 chars, without -, _(*14)

 2xxx - xxxx - xxxx - xxxx - xxxx - xxxx - xxxx - xxxx
 ^ ^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^   ^^^^   ^^^^ ^^^^^^
ver type          timestamp         shard  vendor remain

• version: position 0, 1 char, _(*15)

  • this uuid lib version, _(*16)

  • default to 2, _(*17)

• data type: position 1 - 4, 4 chars, _(*18)

  • 16bit, 65535, _(*19)

  • lib reserves types 1***, _(*20)

  • custom types starts from [2-f]***, _(*21)

• timestamp: position 5 - 19, 15 chars, _(*22)

  • 60bit, _(*23)

  • can be used for at least 360 years, _(*24)

• shard: position 20 - 23, 4 chars, _(*25)

  • 16bit, 65535, _(*26)

  • for sharding purpose, provided by user, _(*27)

• vendor: position 24 - 27 (4 chars), _(*28)

  • vendor id provided by user

• remain: position 28 - 31 (4 chars), _(*29)

  • reserved for future usage

Usage

use Phossa2\Uuid\Uuid;

// 2100020bc58eb7f18602000100010000
$uuid = Uuid::get();

// encode/shorten it, can be used in URL
if (Uuid::isValid($uuid)) {
    // AWprUw7urpN8bbQ4LciGNa
    $short = Uuid::encode($uuid);

    // decode
    var_dump($uuid === Uuid::decode($short)); // true
}

Extend Phossa2\Uuid\Uuid with your own settings or algorithm,, _(*30)

class MyUuid extends Uuid
{
    /*
     * use this vendor id
     *
     * {@inheritDoc}
     */
    protected $vendor = '1234';

    /*
     * use this more reliable sequence
     *
     * {@inheritDoc}
     */
    protected function getSequence()
    {
         // ...
    }
}

APIs

• UuidInterface, _(*31)

  • Uuid::get(string $dataType, string $shardId): string

  Both parameters are optional., _(*32)

• UtilityInterface, _(*33)

  • Uuid::isValid(string $uuid): bool

  Check $uuid valid or not., _(*34)

  • Uuid::info(string $uuid): array

  Get detail information about this $uuid including version, type, time, vendor, remain., _(*35)

  • Uuid::encode(string $uuid): string

  Encode $uuid into a short version (base56), _(*36)

  • Uuid::decode(string $string): string

  Decode the short version into full 32-char UUID, _(*37)

Predefined data types

• Generic OID UuidInterface::TYPE_OID, value 1000., _(*38)

• User id UuidInterface::TYPE_USER, value 1010., _(*39)

• Post or article UuidInterface::TYPE_POST, value 1020., _(*40)

• News UuidInterface::TYPE_NEWS, value 1021., _(*41)

• Image UuidInterface::TYPE_IMAGE, value 1030., _(*42)

• Image album UuidInterface::TYPE_ALBUM, value 1031., _(*43)

• Comment UuidInterface::TYPE_COMM, value 1040., _(*44)

• Rating UuidInterface::TYPE_RATE, value 1041., _(*45)

Change log

Please see CHANGELOG from more information., _(*46)

Testing

$ composer test

Contributing

Please see CONTRIBUTE for more information., _(*47)

Dependencies

• PHP >= 5.4.0, _(*48)

• phossa2/shared >= 2.0.21, _(*49)

License

MIT License, _(*50)