1. O que é e para que serve

A biblioteca Ramsey/UUID é o padrão de facto para trabalhar com UUID (Identificador Único Universal) no ecossistema PHP. UUID é um identificador de 128 bits que garante unicidade sem a necessidade de um coordenador centralizado. A biblioteca oferece um conjunto completo de ferramentas para gerar, analisar, validar e serializar UUIDs de todas as versões padrão (v1, v3, v4, v5, v6, v7, v8), além de suporte para formatos personalizados.

Por que usar isso? Em sistemas distribuídos modernos, arquitetura de microsserviços e bancos de dados (especialmente NoSQL), os UUIDs se tornaram indispensáveis. Eles permitem gerar identificadores únicos no cliente ou servidor sem consultar o banco de dados, algo essencial para modos offline, sharding e replicação. A biblioteca Ramsey/UUID resolve o problema de colisões, oferece geração determinística (v3/v5 baseada em hashes) e suporta timestamps (v1/v6/v7), útil para ordenação por data de criação.

A biblioteca é totalmente compatível com PSR-4, PSR-11 (containers), PSR-20 (Clock) e é ativamente mantida pela comunidade. Ela é usada em grandes projetos como Laravel, Symfony, Drupal e CakePHP.

2. Instalação

A instalação é feita via Composer, o gerenciador de pacotes padrão do PHP. Execute na raiz do seu projeto:

composer require ramsey/uuid

Se você precisar apenas de suporte para UUID v4 (aleatório), pode instalar uma versão leve sem dependências de extensões:

composer require ramsey/uuid:^4.0

Para trabalhar com UUID v1 (baseado em tempo), é necessária a extensão ext-uuid (PECL), mas a biblioteca também pode usar código PHP puro. A versão recomendada do PHP é 8.0 ou superior.

3. Início rápido — exemplo mínimo funcional

A maneira mais simples de começar é gerar um UUID v4 (aleatório). Crie um arquivo test.php:

<?php
require_once 'vendor/autoload.php';

use Ramsey\Uuid\Uuid;

// Gerando UUID v4
$uuid = Uuid::uuid4();
echo $uuid->toString(); // Saída: 550e8400-e29b-41d4-a716-446655440000
?>

Execute no terminal: php test.php. Você receberá um identificador único. Isso é tudo que você precisa para uso básico.

4. Principais métodos/funções/classes

Abaixo estão 8 métodos essenciais da biblioteca Ramsey/UUID. Cada método é descrito com assinatura, breve explicação e um exemplo prático.

4.1 Uuid::uuid4() — geração de UUID aleatório (v4)

Assinatura: public static function uuid4(): UuidInterface

Descrição: Gera um UUID versão 4 baseado em um gerador de números aleatórios criptograficamente seguro. É a opção mais popular para a maioria dos casos.

<?php
use Ramsey\Uuid\Uuid;

$uuid = Uuid::uuid4();
echo $uuid->toString(); // Exemplo: 123e4567-e89b-12d3-a456-426614174000
?>

4.2 Uuid::uuid1() — geração de UUID baseado em tempo (v1)

Assinatura: public static function uuid1(?string $node = null, ?int $clockSeq = null): UuidInterface

Descrição: Gera um UUID versão 1 que inclui um timestamp (intervalos de 100 nanossegundos desde 1582) e o endereço MAC do nó. Útil quando você precisa ordenar registros por data de criação.

<?php
use Ramsey\Uuid\Uuid;

// Geração simples
$uuid1 = Uuid::uuid1();
echo $uuid1->toString(); // Exemplo: c232ab00-9414-11ec-b909-0242ac120002
?>

4.3 Uuid::uuid3() — geração de UUID baseado em hash MD5 (v3)

Assinatura: public static function uuid3(UuidInterface|string $ns, string $name): UuidInterface

Descrição: Gera um UUID versão 3 usando hash MD5 de um namespace e um nome. É determinístico: mesmos parâmetros produzem o mesmo UUID.

<?php
use Ramsey\Uuid\Uuid;

$uuid3 = Uuid::uuid3(Uuid::NAMESPACE_DNS, 'exemplo.com');
echo $uuid3->toString(); // Exemplo: 6ba7b810-9dad-31d0-80b4-00c04fd430c8
?>

4.4 Uuid::uuid5() — geração de UUID baseado em hash SHA-1 (v5)

Assinatura: public static function uuid5(UuidInterface|string $ns, string $name): UuidInterface

Descrição: Similar ao v3, mas usa SHA-1 em vez de MD5. Recomendado sobre o v3 por ser mais seguro.

<?php
use Ramsey\Uuid\Uuid;

$uuid5 = Uuid::uuid5(Uuid::NAMESPACE_URL, 'https://exemplo.com');
echo $uuid5->toString(); // Exemplo: 6ba7b811-9dad-51d0-80b4-00c04fd430c8
?>

4.5 Uuid::uuid6() — geração de UUID ordenável por tempo (v6)

Assinatura: public static function uuid6(?int $node = null, ?int $clockSeq = null): UuidInterface

Descrição: Versão 6 é uma reordenação do v1 para melhor ordenação em bancos de dados. O timestamp vem primeiro, facilitando índices B-tree.

<?php
use Ramsey\Uuid\Uuid;

$uuid6 = Uuid::uuid6();
echo $uuid6->toString(); // Exemplo: 1ec9414c-232a-6b00-b909-0242ac120002
?>

4.6 Uuid::uuid7() — geração de UUID com timestamp Unix (v7)

Assinatura: public static function uuid7(?int $node = null, ?int $clockSeq = null): UuidInterface

Descrição: Versão 7 usa timestamp Unix em milissegundos, combinado com aleatoriedade. Ideal para aplicações modernas que precisam de ordenação temporal.

<?php
use Ramsey\Uuid\Uuid;

$uuid7 = Uuid::uuid7();
echo $uuid7->toString(); // Exemplo: 018f3a6b-7c8d-7e00-8000-000000000000
?>

4.7 Uuid::fromString() — parsing de UUID a partir de string

Assinatura: public static function fromString(string $uuid): UuidInterface

Descrição: Converte uma string UUID válida em um objeto UuidInterface. Útil para validar e manipular UUIDs existentes.

<?php
use Ramsey\Uuid\Uuid;

$uuid = Uuid::fromString('550e8400-e29b-41d4-a716-446655440000');
echo $uuid->getVersion(); // Saída: 4
?>

4.8 Uuid::isValid() — validação de UUID

Assinatura: public static function isValid(string $uuid): bool

Descrição: Verifica se uma string é um UUID válido. Retorna true ou false.

<?php
use Ramsey\Uuid\Uuid;

$valido = Uuid::isValid('550e8400-e29b-41d4-a716-446655440000');
echo $valido ? 'Válido' : 'Inválido'; // Saída: Válido

$invalido = Uuid::isValid('texto-qualquer');
echo $invalido ? 'Válido' : 'Inválido'; // Saída: Inválido
?>

5. Conclusão

A biblioteca Ramsey/UUID é uma ferramenta essencial para qualquer desenvolvedor PHP que trabalhe com sistemas distribuídos, bancos de dados modernos ou precise de identificadores únicos sem depender de um banco central. Com suporte a múltiplas versões de UUID, instalação simples via Composer e uma API intuitiva, ela se destaca como a melhor opção no ecossistema PHP.

Comece instalando a biblioteca hoje mesmo e explore os exemplos deste guia para implementar UUIDs nos seus projetos de forma eficiente e segura.