README

介绍
- 如何安装
- 代码质量
示例
UUID版本
- 为什么使用UUID v1、3、4和5而不是2？
- 何时使用哪个版本？
类概述
类常量
类方法

介绍

该库是PHP的单类UUID数据模型，支持UUID版本1、3、4和5。创建这个库的原因是许多UUID库都非常大，包含很多冗余。这个库旨在作为一个单独的类文件来处理所有的UUID需求。

如何安装

只需将 src/Uuid.php 复制到您的项目中，或通过 composer require garrcomm/uuid 安装

代码质量

使用多个工具检查代码质量，以确保一切正常且文档完善。以下方法是使用的：

PHP Code Sniffer
- 完全遵守 PSR-12
- 需要通用的和某些PEAR DocBlock
PHPUnit
- 100%代码覆盖率
PHPStan
- 使用规则级别9

示例

// Create a default UUID version 1
$uuid = Garrcomm\Uuid::newV1();
echo $uuid; // 8e8bb6e0-daee-11ed-82fa-e7446a136fc7

// Create a UUID version 1 with a specific timestamp
$uuid = Garrcomm\Uuid::newV1(strtotime('1983-08-11 16:00:00'));
echo $uuid; // 98d14000-5fc9-11c1-bacc-e7446a136fc7
echo $uuid->getDateTime()->format(DateTimeInterface::RFC3339); // 1983-08-11T16:00:00+00:00
echo $uuid->getNode(); // e7:44:6a:13:6f:c7

// Create a UUID version 1 with a specific timestamp and node
$uuid = Garrcomm\Uuid::newV1(strtotime('1983-08-11 16:00:00'), 'ab:cd:ef:01:23:45');
echo $uuid; // 98d14000-5fc9-11c1-8b40-abcdef012345

// Create instance based on an existing UUID
$uuid = new Garrcomm\Uuid('98d14000-5fc9-11c1-8b40-abcdef012345');
echo $uuid->getDateTime()->format(DateTimeInterface::RFC3339); // 1983-08-11T16:00:00+00:00

// Create a namespaced version 3 UUID
$uuid = Garrcomm\Uuid::newV3('https://www.stefanthoolen.nl/', Garrcomm\Uuid::NAMESPACE_URL);
echo $uuid; // b288873f-2f8b-366d-86f6-0e024ad3cfb6

// Create a default UUID version 4
$uuid = Garrcomm\Uuid::newV4();
echo $uuid; // efdbd62e-f38a-4e36-aac9-983634b7e78c

还内置了JSON支持；

$uuid = Garrcomm\Uuid::newV1();
echo json_encode($uuid, JSON_PRETTY_PRINT);

结果为

{
    "uuid": "bf23c020-db72-11ed-99a5-842282ee5183",
    "numeric": 2.5406817441082786e+38,
    "version": 1,
    "variant": "RFC_4122",
    "timestamp": {
        "date": "2023-04-15 09:48:59.789930",
        "timezone_type": 1,
        "timezone": "+00:00"
    },
    "node": "84:22:82:ee:51:83"
}

UUID版本

为什么使用UUID v1、3、4和5而不是2？

也许，在未来，将添加对UUIDv2的支持，但根据我的看法，实际上并没有很好的用例。由于UUID中存储的所有数据，使用版本2，在7分钟的时间段内只能生成64个唯一的ID。

何时使用哪个版本？

并不是v5比v1更好。它们是不同的。考虑到安全和唯一性，这个表格可以帮助你选择

版本	唯一性	隐私	安全	描述
UUID v1	⭐⭐⭐⭐⭐	⭐	⭐⭐	包含时间戳和计算机节点。你可能希望将其保持私有，但它使UUID非常独特。
UUID v3	⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	包含命名空间和字符串。如果使用相同的命名空间和字符串，则始终相同。使用 md5 进行哈希处理。
UUID v4	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	完全随机。不包含可预测或个人数据，但UUID在世界上的某个地方存在的可能性非常小。
UUID v5	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	与UUID v3完全相同，但使用 sha1 进行哈希处理。

确实，星级评分并不完全精确，但可以帮助做出决定。

隐私是根据可以从UUID中提取的数据来判断的。MD5也容易受到某些用例的影响（来源），因此v5比v3更安全，理论上可以从UUIDv3中提取数据。

类概述

class Uuid implements JsonSerializable {

    /* Constants */
    public const NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
    public const NAMESPACE_ISO_OID = '6ba7b812-9dad-11d1-80b4-00c04fd430c8';
    public const NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
    public const NAMESPACE_X500 = '6ba7b814-9dad-11d1-80b4-00c04fd430c8';
    public const NIL = '00000000-0000-0000-0000-000000000000';
    public const VARIANT_NCS = 0b0;
    public const VARIANT_RFC_4122 = 0b10;
    public const VARIANT_MICROSOFT_GUID = 0b110;
    public const VARIANT_RESERVED_FUTURE_USE = 0b1110;

    /* Methods */
    public __construct(string $data)
    public __toString(): string
    public getBinaryValue(): string
    public getDateTime(): ?DateTime
    public getFormatted(): string
    public getNode(): ?string
    public getNumericValue(): float
    public getUnixTimestamp(): ?float
    public getUuidTimestamp(): ?int
    public getVariant(): int
    public getVersion(): int
    public jsonSerialize()
    public static newV1(?float $timestamp = null, ?string $node = null): self
    public static newV3(string $nameString, string $namespace = Uuid::NIL): self
    public static newV4(): self
    public static newV5(string $nameString, string $namespace = Uuid::NIL): self
}

常量

Uuid::NAMESPACE_DNS
作为名称字符串的完全限定域名预定义命名空间

Uuid::NAMESPACE_ISO_OID
作为名称字符串的ISO对象标识符预定义命名空间

Uuid::NAMESPACE_URL
作为名称字符串的URL预定义命名空间

Uuid::NAMESPACE_X500
作为名称字符串的X.500区分名称预定义命名空间

Uuid::NIL
一个 nil/null 命名空间；完全为空，但合法。

Uuid::VARIANT_MICROSOFT_GUID
UUID变体是Microsoft GUID。

Uuid::VARIANT_NCS
UUID变体保留用于NCS向后兼容。

Uuid::VARIANT_RESERVED_FUTURE_USE
UUID变体保留供将来使用。

Uuid::VARIANT_RFC_4122
UUID变体符合RFC-4122。

方法

Uuid::__construct — 返回一个新的UUID对象
Uuid::__toString — 将UUID对象转换为字符串
Uuid::getBinaryValue — 返回UUID作为16字节的二进制值
Uuid::getDateTime — 返回UUID的时间戳作为DateTime对象（仅v1）
Uuid::getFormatted — 返回UUID的标准化字符串格式（总是36个字符长）
Uuid::getNode — 返回UUID中的节点（仅v1）
Uuid::getNumericValue — 获取UUID作为浮点值
Uuid::getUnixTimestamp — 返回Unix时间戳
Uuid::getUuidTimestamp — 返回UUID时间戳
Uuid::getVariant — 返回UUID变体
Uuid::getVersion — 返回UUID版本
Uuid::jsonSerialize — 返回此对象，准备进行JSON序列化
Uuid::newV1 — 返回一个新的UUID对象，填充了唯一的v1 UUID
Uuid::newV3 — 返回一个新的UUID对象，填充了v3 UUID
Uuid::newV4 — 返回一个新的UUID对象，填充了唯一的v4 UUID
Uuid::newV5 — 返回一个新的UUID对象，填充了v5 UUID

Uuid::__construct

描述

public Uuid::__construct(string $data)

返回一个新的UUID对象

参数

data
此UUID的数据。支持以下三种格式；
1. 二进制；16字节/128位字符串
2. 规范文本表示：00000000-0000-0000-0000-000000000000
3. 用括号包围表示：{00000000-0000-0000-0000-000000000000}
4. 作为统一资源名称：urn:uuid:00000000-0000-0000-0000-000000000000。

错误/异常

当UUID格式不正确时抛出InvalidArgumentException。

Uuid::__toString

描述

public Uuid::__toString(): string

将UUID对象转换为字符串

返回值

格式为00000000-0000-0000-0000-000000000000的字符串

Uuid::getBinaryValue

描述

public Uuid::getBinaryValue(): string

返回UUID作为16字节二进制值

返回值

16字节的字符串

Uuid::getDateTime

描述

public Uuid::getDateTime(): ?DateTime

返回UUID的时间戳作为DateTime对象（仅v1）

返回值

DateTime对象，或当没有可用的时间戳时返回null

Uuid::getFormatted

描述

public Uuid::getFormatted(): string

返回UUID的标准化字符串格式（总是36个字符长）

返回值

格式为00000000-0000-0000-0000-000000000000的字符串

Uuid::getNode

描述

public Uuid::getNode(): ?string

返回UUID中的节点（仅v1）

返回值

格式为17:28:39:4a:5b:6c的节点，或当没有可用节点时返回null

Uuid::getNumericValue

描述

public Uuid::getNumericValue(): float

获取UUID作为浮点值

返回值

返回128位整数

Uuid::getUnixTimestamp

描述

public Uuid::getUnixTimestamp(): ?float

返回 Unix 时间戳

返回值

自 1970-01-01 00:00:00 UTC 以来经过的秒数，作为浮点数（包含微秒）
当没有时间戳可用时返回 null

Uuid::getUuidTimestamp

描述

public Uuid::getUuidTimestamp(): ?int

返回 UUID 时间戳

返回值

自 1582-10-15 00:00:00 UTC 以来经过的秒数，以 100 纳秒为单位，当没有时间戳可用时返回 null。

Uuid::getVariant

描述

public Uuid::getVariant(): int

返回 UUID 变体

返回值

匹配 Uuid::VARIANT_ 常量之一的整数

Uuid::getVersion

描述

public Uuid::getVersion(): int

返回 UUID 版本

返回值

UUID 版本（1、3、4 或 5）

Uuid::jsonSerialize

描述

public Uuid::jsonSerialize()

返回此对象，已准备好进行 json 序列化

返回值

此对象，已准备好进行 json 序列化

Uuid::newV1

描述

public static Uuid::newV1(?float $timestamp = null, ?string $node = null): self

返回一个新 UUID 对象，包含一个唯一的 v1 UUID 时间戳

参数

时间戳
UUID 的时间戳（null = 当前时间戳）。
节点
节点字符串（null = 自动检测）。

返回值

包含版本 1 UUID 的 UUID 对象

错误/异常

当UUID格式不正确时抛出InvalidArgumentException。

Uuid::newV3

描述

public static Uuid::newV3(string $nameString, string $namespace = Uuid::NIL): self

返回一个新 UUID 对象，包含一个 v3 UUID

参数

nameString
输入字符串。
namespace
命名空间 UUID（Uuid::NAMESPACE_ 常量之一，或自定义命名空间）。

返回值

包含版本 3 UUID 的 UUID 对象

错误/异常

当UUID格式不正确时抛出InvalidArgumentException。

Uuid::newV4

描述

public static Uuid::newV4(): self

返回一个新 UUID 对象，包含一个唯一的 v4 UUID

返回值

包含版本 4 UUID 的 UUID 对象

Uuid::newV5

描述

public static Uuid::newV5(string $nameString, string $namespace = Uuid::NIL): self

返回一个新 UUID 对象，包含一个 v5 UUID

参数

nameString
输入字符串。
namespace
命名空间 UUID（static::NAMESPACE_ 常量之一，或自定义命名空间）。

返回值

包含版本 5 UUID 的 UUID 对象

错误/异常

当UUID格式不正确时抛出InvalidArgumentException。

garrcomm / uuid

维护者

详细信息

README

介绍

如何安装

代码质量

示例

UUID版本

为什么使用UUID v1、3、4和5而不是2？

何时使用哪个版本？

类概述

常量

方法

Uuid::__construct

描述

参数

错误/异常

Uuid::__toString

描述

返回值

Uuid::getBinaryValue

描述

返回值

Uuid::getDateTime

描述

返回值

Uuid::getFormatted

描述

返回值

Uuid::getNode

描述

返回值

Uuid::getNumericValue

描述

返回值

Uuid::getUnixTimestamp

描述

返回值

Uuid::getUuidTimestamp

描述

返回值

Uuid::getVariant

描述

返回值

Uuid::getVersion

描述

返回值

Uuid::jsonSerialize

描述

返回值

Uuid::newV1

描述

参数

返回值

错误/异常

Uuid::newV3

描述

参数

返回值

错误/异常

Uuid::newV4

描述

返回值

Uuid::newV5

描述

参数

返回值

错误/异常