1. 什么是 Ramsey/UUID？为什么需要它？

Ramsey/UUID 是 PHP 生态中处理 UUID（通用唯一标识符）的事实标准库。UUID 是一个 128 位的标识符，无需中央协调器即可保证全局唯一性。该库提供了一整套工具，用于生成、解析、验证和序列化所有标准版本的 UUID（v1、v3、v4、v5、v6、v7、v8），并支持非标准格式。

为什么需要它？在现代分布式系统、微服务架构和数据库（尤其是 NoSQL）中，UUID 已成为不可或缺的组件。它允许在客户端或服务器端生成唯一标识符，无需访问数据库，这对于离线模式、分片和复制至关重要。Ramsey/UUID 库解决了冲突问题，支持基于哈希的确定性生成（v3/v5），并包含时间戳（v1/v6/v7），便于按创建时间排序。

该库完全支持 PSR-4、PSR-11（容器）、PSR-20（时钟），并得到社区的积极维护。它被用于 Laravel、Symfony、Drupal 和 CakePHP 等大型项目中。

2. 安装指南

通过 Composer（PHP 的标准包管理器）进行安装。在项目根目录下执行：

composer require ramsey/uuid

如果你只需要 UUID v4（随机）支持，可以安装轻量版，无需扩展依赖：

composer require ramsey/uuid:^4.0

使用 UUID v1（基于时间）需要 ext-uuid 扩展（PECL），但库也可以使用纯 PHP 代码。推荐 PHP 版本为 8.0 或更高。

3. 快速入门——最小工作示例

最简单的开始方式是生成一个 UUID v4（随机）。创建文件 test.php：

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

use Ramsey\Uuid\Uuid;

// 生成 UUID v4
$uuid = Uuid::uuid4();
echo $uuid->toString(); // 输出：550e8400-e29b-41d4-a716-446655440000
?>

在终端运行：php test.php。你将获得一个唯一标识符。这就是基本使用的全部内容。

4. 核心方法/函数/类详解

以下是 Ramsey/UUID 库的 8 个关键方法。每个方法都包含签名、简要说明和可运行的示例。

4.1 Uuid::uuid4() —— 生成随机 UUID（v4）

签名： public static function uuid4(): UuidInterface

说明：基于密码学安全的随机数生成器生成版本 4 的 UUID。这是大多数场景下最流行的选择。

<?php
use Ramsey\Uuid\Uuid;

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

4.2 Uuid::uuid1() —— 基于时间生成 UUID（v1）

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

说明：生成版本 1 的 UUID，包含时间戳（自 1582 年以来的 100 纳秒间隔）和节点 MAC 地址。适用于需要按创建时间排序记录的场景。

<?php
use Ramsey\Uuid\Uuid;

// 简单生成
$uuid1 = Uuid::uuid1();
echo $uuid1->toString(); // 示例：c232ab00-9414-11ec-b909-0242ac120002
?>