后端【免费下载链接】uuid:snowflake: A PHP library for generating universally unique identifiers (UUIDs).项目地址https://gitcode.com/gh_mirrors/uui/uuid点击查看免费下载导读ramsey/uuid当前仓库gh_mirrors/uui/uuid除面向对象 API 外还在Ramsey\Uuid命名空间下提供 8 个轻量级全局辅助函数v1()v8()。它们覆盖 RFC 9562前身 RFC 4122定义的全部 8 个版本 UUID 生成能力与静态方法最大的区别是辅助函数直接返回 UUID 的标准字符串表示string而非 UUID 对象。本文以官方文档 docs/reference/helper.rst 为主线结合 src/functions.php 源码与 tests/FunctionsTest.php 测试用例逐个函数讲解参数语义、默认值、调用链与典型用法帮助你根据业务场景时间序、随机、命名哈希、自定义格式快速选型。辅助函数总览只为字符串而来官方文档开门见山地指出ramsey/uuid additionally provides the following helper functions, which return only the string standard representation of a UUID——这些函数只返回 UUID 的标准字符串表示即形如xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx的 36 字符形式不做任何对象包装。全部 8 个函数定义在 src/functions.php实现模式高度统一调用Uuid::uuidX()静态方法拿到对象再链式调用-toString()转成字符串。例如v1()的完整实现只有一行// src/functions.php L32-L35 function v1($node null, ?int $clockSeq null): string { return Uuid::uuid1($node, $clockSeq)-toString(); }函数签名速查表来自 src/functions.php函数对应版本必填参数可选参数返回v1()版本 1Gregorian 时间—$node、$clockSeqstringv2()版本 2DCE Security$localDomain$localIdentifier、$node、$clockSeqstringv3()版本 3命名空间 MD5$ns、$name—stringv4()版本 4随机——stringv5()版本 5命名空间 SHA-1$ns、$name—stringv6()版本 6重排 Gregorian 时间—$node、$clockSeqstringv7()版本 7Unix Epoch 时间—$dateTimestringv8()版本 8自定义格式$bytes—string注意官方文档中v7()的参数描述为\DatetimeInterface|null $node这是文档笔误。源码 src/functions.php 中该参数实际名为$dateTime类型为?DateTimeInterface。函数如何被加载Composer autoload files这些全局函数能直接使用靠的是 Composer 的autoload.files机制。在 composer.json 中// composer.json L47-L54 autoload: { psr-4: { Ramsey\\Uuid\\: src/ }, files: [ src/functions.php ] }这意味着执行composer require ramsey/uuid安装方式详见 docs/quickstart.rst后functions.php会被自动加载无需手动require。需要注意的是函数定义在Ramsey\Uuid命名空间下调用时需使用use function Ramsey\Uuid\v4;导入或写全限定名Ramsey\Uuid\v4()。另外函数体顶部有declare(strict_types1);文件依赖 PHP 8.0见 composer.json 的require段。v1()版本 1 时间 UUIDv1($node null, $clockSeq null): string生成版本 1Gregorian 时间UUID 的字符串表示基于当前时间、48 位节点地址通常是网卡 MAC与 14 位时钟序列。$node可选节点地址类型可为Ramsey\Uuid\Type\Hexadecimal、int或string十六进制字符串表示 48 位硬件地址。缺省时由节点提供器自动决定从源码结构看默认走SystemNodeProvider/RandomNodeProvider等见 src/Provider/Node。$clockSeq可选时钟序列?int14 位数字用于在系统时钟回拨或节点 ID 变化时避免重复。缺省时随机生成。调用链v1()→Uuid::uuid1()src/Uuid.php→ 工厂的timeGenerator-generate($node, $clockSeq)src/UuidFactory.php。use function Ramsey\Uuid\v1; $uuid v1(); // 形如5c9e6a20-8b3f-11ee-a7d9-0242ac120002v2()版本 2 DCE Security UUIDv2(int $localDomain, ?IntegerObject $localIdentifier null, ?Hexadecimal $node null, ?int $clockSeq null): string生成版本 2DCE SecurityUUID 字符串在时间戳基础上嵌入本地域与本地标识符适用于 DCE 安全上下文中的对象标识。$localDomain必填本地域取值为Uuid::DCE_DOMAIN_PERSON0用户、Uuid::DCE_DOMAIN_GROUP1用户组或Uuid::DCE_DOMAIN_ORG2组织三者之一常量定义见 src/Uuid.php。$localIdentifier域对应的本地标识符Ramsey\Uuid\Type\Integer默认取系统 UIDperson 域或 GIDgroup 域。$node可选 48 位十六进制节点地址。$clockSeq可选时钟序列在版本 2 中该数字的低 8 位会被域domain替换见 src/Uuid.php 的注释说明。测试用例 tests/FunctionsTest.php 给出了完整的显式传参写法use Ramsey\Uuid\Type\Hexadecimal; use Ramsey\Uuid\Type\Integer as IntegerObject; use function Ramsey\Uuid\v2; $v2 v2( Uuid::DCE_DOMAIN_PERSON, new IntegerObject(1004), new Hexadecimal(aabbccdd0011), 63 );v3() / v5()命名空间 哈希的确定性 UUIDv3($ns, string $name): string // MD5 哈希 v5($ns, string $name): string // SHA-1 哈希基于「命名空间 UUID 名称字符串」做哈希生成确定性的名称型 UUID同样的$ns与$name永远产出同样的 UUID适合为 URL、邮箱、域名等生成稳定标识。$ns命名空间可以是Ramsey\Uuid\UuidInterface实例或合法 UUID 字符串。$name要生成标识符的名称字符串。Uuid类预置了 4 个 RFC 9562 分配的命名空间常量src/Uuid.php常量值语义Uuid::NAMESPACE_DNS6ba7b810-9dad-11d1-80b4-00c04fd430c8名称是完整域名FQDNUuid::NAMESPACE_URL6ba7b811-9dad-11d1-80b4-00c04fd430c8名称是 URLUuid::NAMESPACE_OID6ba7b812-9dad-11d1-80b4-00c04fd430c8名称是 ISO OIDUuid::NAMESPACE_X5006ba7b814-9dad-11d1-80b4-00c04fd430c8名称是 X.500 DNuse Ramsey\Uuid\Uuid; use function Ramsey\Uuid\v3; use function Ramsey\Uuid\v5; $v3 v3(Uuid::NAMESPACE_URL, https://example.com/foo); // MD5 版本 $v5 v5(Uuid::NAMESPACE_URL, https://example.com/foo); // SHA-1 版本 // v5 与 v3 均可复现同一命名空间 名称 → 同一 UUID工厂层通过uuidFromNsAndName($ns, $name, $version, md5|sha1)实现src/UuidFactory.php对应的测试断言见 tests/FunctionsTest.php。两版本的差别v3 用 MD5128 位安全性较低v5 用 SHA-1160 位截断RFC 建议新应用优先选 v5。v4()随机 UUIDv4(): string生成版本 4随机UUID不接收任何参数也无需任何输入。底层由随机生成器产出 16 字节随机数据再打上版本第 48-51 位与变体第 64-65 位标记见 src/UuidFactory.php 中randomGenerator-generate(16)的调用。use function Ramsey\Uuid\v4; $uuid v4(); // 形如3f4b9f1e-6c2d-4a1b-9d8e-2f7a0c5b4d3ev4 是绝大多数业务场景订单号、会话 ID、主键替代的默认选择无需配置即可使用。v6()版本 6 重排时间 UUIDv6(?Hexadecimal $node null, ?int $clockSeq null): string生成版本 6reordered Gregorian timeUUID。与 v1 一样基于时间 节点 时钟序列但对时间字段做了字节重排使时间信息在字符串中按从高位到低位的顺序排列从而支持按字典序排序约等于按时间排序利于数据库索引与范围查询。参数含义与v1()一致$node为可选十六进制节点$clockSeq为可选时钟序列。底层实现值得关注工厂先复用timeGenerator生成 v1 字节再按 v6 规范重排时间相关字节src/UuidFactory.php。use Ramsey\Uuid\Type\Hexadecimal; use function Ramsey\Uuid\v6; $v6 v6(new Hexadecimal(aabbccdd0011), 1234);对应测试见 tests/FunctionsTest.php。v7()版本 7 Unix Epoch 时间 UUIDv7(?DateTimeInterface $dateTime null): string生成版本 7Unix Epoch timeUUID。这是时间排序友好型 UUID 的现代推荐方案前 48 位存放自 Unix 纪元起的毫秒时间戳其余位填充随机数据天然具备时间有序性且无 v1/v6 所需的节点地址。$dateTime可选日期时间对象DateTimeInterface用于指定生成 UUID 的时间点不传时使用当前时间。use DateTimeImmutable; use function Ramsey\Uuid\v7; $now v7(); $at v7(new DateTimeImmutable(2022-09-14T22:44:3300:00));测试 tests/FunctionsTest.php 验证了传入自定义时间时生成的 UUID 能还原出精确时间戳1663195473。工厂实现中v7 由独立的UnixTimeGenerator生成src/UuidFactory.php源码位于 src/Generator/UnixTimeGenerator.php。v8()版本 8 自定义格式 UUIDv8(string $bytes): string生成版本 8implementation-specific自定义格式UUID允许你把任意 16 字节数据塞进 UUID。$bytes必填16 字节的八位组字符串octet string是一块可由你自由填充 128 位信息的开放数据。官方文档特别强调了两条硬性约束源码注释也原样保留src/functions.php、src/Uuid.php第 48–51 位会被替换为版本字段version 8第 64–65 位会被替换为变体字段variant。即你提供的 128 位数据中这 6 位并不能原样保留绝不能依赖这些位承载业务数据。另外自定义内容只有你的应用能理解其他应用无法解释其语义。use function Ramsey\Uuid\v8; $v8 v8(\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xaa\xbb\xcc\xdd\xee\xff);工厂实现直接调用uuidFromBytesAndVersion($bytes, Uuid::UUID_TYPE_CUSTOM)src/UuidFactory.php测试断言见 tests/FunctionsTest.php。辅助函数 vs 静态方法如何选择同样是生成 UUID辅助函数与Uuid::uuidX()静态方法src/Uuid.php的区别仅在返回类型维度辅助函数v1()v8()静态方法Uuid::uuid1()uuid8()返回类型string标准字符串表示UuidInterface对象典型用法日志、拼接、直接入库、字符串拼接需要调用getDateTime()、getFields()、比较、序列化等对象能力适用场景只关心「得到一个合法 UUID 字符串」需要后续对 UUID 做解析、排序、类型判断辅助函数适合快速原型与一次性字符串生成如果需要从 UUID 中取时间如getDateTime()、校验版本或做对象级操作应改用静态方法获取对象。静态方法对应的各版本详细行为可进一步阅读 docs/reference/uuid.rst 及各版本文档如 docs/rfc4122/version7.rst。使用建议小结纯随机主键/标识直接用v4()零参数零配置。需要按时间排序且接受随机性优先v7()毫秒时间戳在字符串高位字典序≈时间序数据库索引友好。需要确定性的名称标识同一输入同一输出用v5()SHA-1需配合Uuid::NAMESPACE_*常量或自定义命名空间。需要传统时间 节点语义用v1()/v6()v6 排序更优。DCE 安全上下文用v2()并传入DCE_DOMAIN_*常量。完全自定义的 128 位布局用v8()但务必避开第 48–51 位版本与第 64–65 位变体。所有函数返回的字符串均可通过Uuid::fromString()还原为对象继续处理例如Uuid::fromString(v7())-getDateTime()可提取生成时间。赞分享后端【免费下载链接】uuid:snowflake: A PHP library for generating universally unique identifiers (UUIDs).项目地址https://gitcode.com/gh_mirrors/uui/uuid点击查看免费下载相关推荐CF-Workers-Raw自动化部署使用GitHub Actions一键部署指南CF Workers Raw自动化部署使用GitHub Actions一键部署指南 CF Workers Raw是一个通过Cloudflare Workers网页打包工具革新无需代码经验3分钟将任意网站变桌面应用网页打包工具革新无需代码经验3分钟将任意网站变桌面应用 还在为复杂的桌面应用开发流程头疼吗传统方法需要安装开发环境、学习框架、配置构建工具整个过程耗时耗开发工具桌面应用移动开发跨平台彻底搞懂UUID编码格式ramsey/uuid支持的5种字符串转换方案彻底搞懂UUID编码格式ramsey/uuid支持的5种字符串转换方案 你是否曾遇到UUID在数据库存储时排序混乱或者在Windows系统中处理GUID格式后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
