1. ¿Qué es y para qué sirve?

La librería Ramsey/UUID es el estándar de facto para trabajar con UUID (Identificador Único Universal) en el ecosistema PHP. Un UUID es un identificador de 128 bits que garantiza unicidad sin necesidad de un coordinador centralizado. Esta librería ofrece un conjunto completo de herramientas para generar, analizar, validar y serializar UUID de todas las versiones estándar (v1, v3, v4, v5, v6, v7, v8), además de soporte para formatos no estándar.

¿Para qué sirve? En los sistemas distribuidos modernos, la arquitectura de microservicios y las bases de datos (especialmente NoSQL), los UUID se han vuelto indispensables. Permiten generar identificadores únicos desde el cliente o servidor sin consultar la base de datos, algo crítico para modos offline, sharding y replicación. Ramsey/UUID resuelve el problema de colisiones, ofrece generación determinista (v3/v5 basadas en hashes) y soporta marcas de tiempo (v1/v6/v7), útiles para ordenar por fecha de creación.

La librería es compatible con PSR-4, PSR-11 (contenedores), PSR-20 (Clock) y cuenta con un mantenimiento activo por parte de la comunidad. Se utiliza en proyectos tan importantes como Laravel, Symfony, Drupal y CakePHP.

2. Instalación

La instalación se realiza mediante Composer, el gestor de paquetes estándar de PHP. Ejecuta en la raíz de tu proyecto:

composer require ramsey/uuid

Si solo necesitas soporte para UUID v4 (aleatorios), puedes instalar la versión ligera sin dependencias de extensiones:

composer require ramsey/uuid:^4.0

Para trabajar con UUID v1 (basados en tiempo) se requiere la extensión ext-uuid (PECL), aunque la librería también puede usar código PHP puro. La versión recomendada de PHP es 8.0 o superior.

3. Inicio rápido — ejemplo mínimo funcional

La forma más sencilla de empezar es generar un UUID v4 (aleatorio). Crea un archivo test.php:

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

use Ramsey\Uuid\Uuid;

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

Ejecuta desde la consola: php test.php. Obtendrás un identificador único. Esto es todo lo que necesitas para un uso básico.

4. Métodos, funciones y clases principales

A continuación se presentan 8 métodos clave de la librería Ramsey/UUID. Cada método incluye su firma, una breve descripción y un ejemplo funcional.

4.1 Uuid::uuid4() — generar UUID aleatorio (v4)

Firma: public static function uuid4(): UuidInterface

Descripción: Genera un UUID versión 4 basado en un generador de números aleatorios criptográficamente seguro. Es la opción más popular para la mayoría de los casos.

<?php
use Ramsey\Uuid\Uuid;

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

4.2 Uuid::uuid1() — generar UUID basado en tiempo (v1)

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

Descripción: Genera un UUID versión 1 que incluye una marca de tiempo (intervalos de 100 nanosegundos desde 1582) y la dirección MAC del nodo. Útil cuando necesitas ordenar registros por fecha de creación.

<?php
use Ramsey\Uuid\Uuid;

// Generación simple
$uuid1 = Uuid::uuid1();
echo $uuid1->toString(); // Ejemplo: c232ab00-9414-11ec-b909-0242ac120002
?>

4.3 Uuid::uuid3() — generar UUID basado en hash MD5 (v3)

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

Descripción: Genera un UUID versión 3 a partir de un namespace y un nombre, usando MD5. Es determinista: mismos datos producen el mismo UUID.

<?php
use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;

$uuid3 = Uuid::uuid3(Uuid::NAMESPACE_DNS, 'ejemplo.com');
echo $uuid3->toString(); // Ejemplo: 9073926b-929f-31c2-abc9-fad77ae3e8eb
?>

4.4 Uuid::uuid5() — generar UUID basado en hash SHA-1 (v5)

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

Descripción: Similar a v3 pero usando SHA-1. Más seguro y recomendado sobre v3.

<?php
use Ramsey\Uuid\Uuid;

$uuid5 = Uuid::uuid5(Uuid::NAMESPACE_URL, 'https://ejemplo.com/articulo/123');
echo $uuid5->toString(); // Ejemplo: 4d855b6e-1c4a-5f3e-9b8a-7c2d1e0f3a4b
?>

4.5 Uuid::uuid6() — generar UUID reordenado por tiempo (v6)

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

Descripción: Versión 6 de UUID, similar a v1 pero con los bits de tiempo reordenados para mejorar el rendimiento en bases de datos. Ideal para claves primarias ordenables.

<?php
use Ramsey\Uuid\Uuid;

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

4.6 Uuid::uuid7() — generar UUID con timestamp Unix (v7)

Firma: public static function uuid7(?int $timestamp = null): UuidInterface

Descripción: UUID versión 7 que incluye un timestamp Unix en milisegundos. Es el más moderno y recomendado para nuevas aplicaciones, ya que es ordenable y compatible con sistemas distribuidos.

<?php
use Ramsey\Uuid\Uuid;

$uuid7 = Uuid::uuid7();
echo $uuid7->toString(); // Ejemplo: 018f3a6b-7c8d-7e9f-8a0b-1c2d3e4f5a6b
?>

4.7 Uuid::fromString() — crear UUID desde un string

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

Descripción: Parsea un string UUID válido y devuelve un objeto UuidInterface. Lanza una excepción si el formato es inválido.

<?php
use Ramsey\Uuid\Uuid;

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

4.8 Uuid::isValid() — validar si un string es un UUID

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

Descripción: Verifica si un string tiene el formato UUID válido. No valida la versión ni la variante, solo la estructura.

<?php
use Ramsey\Uuid\Uuid;

$esValido = Uuid::isValid('550e8400-e29b-41d4-a716-446655440000');
var_dump($esValido); // bool(true)

$esValido2 = Uuid::isValid('esto-no-es-un-uuid');
var_dump($esValido2); // bool(false)
?>

5. Conclusión

Ramsey/UUID es una librería robusta, bien documentada y ampliamente adoptada en el ecosistema PHP. Ya sea que necesites identificadores aleatorios (v4), ordenables por tiempo (v1, v6, v7) o deterministas (v3, v5), esta librería cubre todos los casos de uso. Su integración con Composer, el soporte para múltiples versiones de UUID y el rendimiento optimizado la convierten en la elección ideal para cualquier proyecto PHP moderno.

Para más información, consulta la documentación oficial o el repositorio en GitHub.