Getting Started

Requirements

ramsey/uuid 4.4.0 requires the following:

The JSON extension is normally enabled by default, but it is possible to disable it. Other required extensions include PCRE and SPL. These standard extensions cannot be disabled without patching PHP’s build system and/or C sources.

ramsey/uuid recommends installing/enabling the following extensions. While not required, these extensions improve the performance of ramsey/uuid.

Install With Composer

The only supported installation method for ramsey/uuid is Composer. Use the following command to add ramsey/uuid to your project dependencies:

composer require ramsey/uuid

Using ramsey/uuid

After installing ramsey/uuid, the quickest way to get up-and-running is to use the static generation methods.

use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid4();

printf(
    "UUID: %s\nVersion: %d\n",
    $uuid->toString(),
    $uuid->getFields()->getVersion()
);

This will return an instance of Ramsey\Uuid\Rfc4122\UuidV4.

Tip

Use the Interfaces

Feel free to use instanceof to check the specific instance types of UUIDs. However, when using type hints, it’s best to use the interfaces.

The most lenient interface is Ramsey\Uuid\UuidInterface, while Ramsey\Uuid\Rfc4122\UuidInterface ensures the UUIDs you’re using conform to the RFC 4122 standard. If you’re not sure which one to use, start with the stricter Rfc4122\UuidInterface.

ramsey/uuid provides a number of helpful static methods that help you work with and generate most types of UUIDs, without any special customization of the library.

Method

Description

Uuid::uuid1()

This generates a Version 1: Time-based UUID.

Uuid::uuid2()

This generates a Version 2: DCE Security UUID.

Uuid::uuid3()

This generates a Version 3: Name-based (MD5) UUID.

Uuid::uuid4()

This generates a Version 4: Random UUID.

Uuid::uuid5()

This generates a Version 5: Name-based (SHA-1) UUID.

Uuid::uuid6()

This generates a Version 6: Ordered-Time UUID.

Uuid::isValid()

Checks whether a string is a valid UUID.

Uuid::fromString()

Creates a UUID instance from a string UUID.

Uuid::fromBytes()

Creates a UUID instance from a 16-byte string.

Uuid::fromInteger()

Creates a UUID instance from a string integer.

Uuid::fromDateTime()

Creates a version 1 UUID instance from a PHP DateTimeInterface.