README

The package provides the ability to use ramsey/identifier as various Cycle ORM entity column types.

Installation

Note: Due to a dependency on ramsey/identifier this package requires PHP 8.2 or newer.

Install this package as a dependency using Composer.

composer require cycle/entity-behavior-identifier

Snowflake Examples

Snowflake: A distributed ID generation system developed by Twitter that produces 64-bit unique, sortable identifiers. Each ID encodes a timestamp, machine ID, and sequence number, enabling high-throughput, ordered ID creation suitable for large-scale distributed applications.

Note: Support for Snowflake identifiers will arrive soon, stay tuned.

ULID Examples

ULID (Universally Unique Lexicographically Sortable Identifier): A 128-bit identifier designed for high uniqueness and lexicographical sortability. It combines a timestamp component with random data, allowing for ordered IDs that can be generated rapidly and are human-readable, making it ideal for databases and distributed systems.

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\ORM\Entity\Behavior\Identifier;
use Ramsey\Identifier\Ulid;

#[Entity]
#[Identifier\Ulid(field: 'id')]
class User
{
    #[Column(type: 'ulid', primary: true)]
    private Ulid $id;
}

UUID Examples

UUID Version 1 (Time-based): Generated using the current timestamp and the MAC address of the computer, ensuring unique identification based on time and hardware.

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\ORM\Entity\Behavior\Identifier;
use Ramsey\Identifier\Uuid;

#[Entity]
#[Identifier\Uuid1(field: 'id')]
class User
{
    #[Column(type: 'uuid', primary: true)]
    private Uuid $id;
}

UUID Version 2 (DCE Security): Similar to version 1 but includes a local identifier such as a user ID or group ID, primarily used in DCE security contexts.

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\ORM\Entity\Behavior\Identifier;
use Ramsey\Identifier\Uuid;

#[Entity]
#[Identifier\Uuid2(field: 'id')]
class User
{
    #[Column(type: 'uuid', primary: true)]
    private Uuid $id;
}

UUID Version 3 (Name-based, MD5): Created by hashing a namespace identifier and name using MD5, resulting in a deterministic UUID based on input data.

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\ORM\Entity\Behavior\Identifier;
use Ramsey\Identifier\Uuid;

#[Entity]
#[Identifier\Uuid3(
    field: 'id',
    namespace: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
    name: 'example.com',
)]
class User
{
    #[Column(type: 'uuid', primary: true)]
    private Uuid $id;
}

UUID Version 4 (Random): Generated entirely from random or pseudo-random numbers, offering high unpredictability and uniqueness.

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\ORM\Entity\Behavior\Identifier;
use Ramsey\Identifier\Uuid;

#[Entity]
#[Identifier\Uuid4(field: 'id')]
class User
{
    #[Column(type: 'uuid', primary: true)]
    private Uuid $id;
}

UUID Version 5 (Name-based, SHA-1): Similar to version 3 but uses SHA-1 hashing, providing a different deterministic UUID based on namespace and name.

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\ORM\Entity\Behavior\Identifier;
use Ramsey\Identifier\Uuid;

#[Entity]
#[Identifier\Uuid5(
    field: 'id',
    namespace: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
    name: 'example.com',
)]
class User
{
    #[Column(type: 'uuid', primary: true)]
    private Uuid $id;
}

UUID Version 6 (Draft/Upcoming): An experimental or proposed version focused on improving time-based UUIDs with more sortable properties (not yet widely adopted).

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\ORM\Entity\Behavior\Identifier;
use Ramsey\Identifier\Uuid;

#[Entity]
#[Identifier\Uuid6(field: 'id')]
class User
{
    #[Column(type: 'uuid', primary: true)]
    private Uuid $id;
}

UUID Version 7 (Draft/Upcoming): A newer proposal designed to incorporate sortable features based on Unix timestamp, enhancing performance in database indexing.

use Cycle\Annotated\Annotation\Column;
use Cycle\Annotated\Annotation\Entity;
use Cycle\ORM\Entity\Behavior\Identifier;
use Ramsey\Identifier\Uuid;

#[Entity]
#[Identifier\Uuid7(field: 'id')]
class User
{
    #[Column(type: 'uuid', primary: true)]
    private Uuid $id;
}

You can find more information about Entity behavior UUID here.

License:

The MIT License (MIT). Please see LICENSE for more information. Maintained by Spiral Scout.