boondoc/uuid

A PHP5.6+ class for handling and generating RFC 4122 versions 1, 3, 4 and 5 Universally Unique Identifiers (UUIDs).

维护者

详情

github.com/boondoc/uuid

源代码

问题

安装: 52

依赖: 0

建议者: 0

安全: 0

星星: 0

监视者: 2

分支: 0

开放问题: 0

1.1.0 2023-03-12 12:18 UTC

Requires

  • php: >=5.6

Requires (Dev)

MIT 7610ad990bdfbeb136a6ec2e3ddf7f16a945101a

  • Nik Mennega

This package is not auto-updated.

Last update: 2024-09-22 19:43:02 UTC

README

Boondoc/uuid 是一个 PHP5.6+ 类，用于处理和生成 RFC 4122 版本 1、3、4 和 5（变体 1）的通用唯一标识符（UUID）。

提供三种字符串输出格式

  • “长”格式是一个标准的 36 个字符字符串（小写，用连字符分隔，没有括号包围）
  • “短”格式是一个 22 个字符的 base64 编码字符串，使用 URL 安全字符，没有填充
  • “二进制”格式是一个 16 个字符的字节 blob（大端编码）

不生成或接受 UUID 变体 0、3 和 5 作为有效输入。

一旦生成，UUID 就被存储并作为字符串处理，没有内部结构——时间戳、时钟序列等都被忽略。不支持对组件字段的排序进行分析和重新排列。

安装

使用 Composer

composer require boondoc/uuid

手动安装

下载文件 uuid.php 并使用 require 语句将其包含在您的代码中。

使用方法

导入类

use Boondoc\uuid;

在创建时，将值分配给 uuid 对象。创建后，对象的值不能被更改，尽管它可以以多种格式检索。

$u = new uuid ([ mixed $uuid = '' [, mixed $namespace = null ] ] );

导入值

传递有效的 UUID 作为 $uuid 参数将尝试将此值分配给新的 uuid 对象。

$u = new uuid ('fae0b286-007f-3824-a616-16d7332b7a09'); // Imports the specified string

请注意，另一个 uuid 对象实例被视为此目的的有效 UUID

$u1 = new uuid ('fae0b286-007f-3824-a616-16d7332b7a09');
$u2 = new uuid ($u1); // Imports the value of $u1 – essentially $u2 is now a clone of $u1

生成随机值

不传递任何参数将生成新的版本 4 UUID 并将其分配给新的 uuid 对象。

$u = new uuid (); // Generates a new UUID v4

生成命名空间值

如果 $uuid 参数不为空，但不是有效的 UUID，则将使用 $uuid 参数作为其“名称”输入生成新的版本 5 UUID，并将其分配给新的 uuid 对象。

如果 $namespace 参数是有效的 UUID，则将其用作版本 5 生成中的“命名空间”参数。

$u1 = new uuid ('String to be hashed', '87e1d1be-df8d-11e7-b804-0800276fa7d4'); // Generates a new UUID v5 using '87e1…' as the namespace
$u2 = new uuid ('String to be hashed', $u1); // Generates a new UUID v5 using $u1 as the namespace

如果省略了 $namespace 参数，或为布尔值 true，则使用默认的“命名空间”参数。在脚本执行开始时，默认命名空间初始化为“nil” UUID，但可以随后将其设置为任何有效的 UUID。

echo new uuid (uuid::getDefaultNamespace ()); // '00000000-0000-0000-0000-000000000000', aka the “nil” UUID

$u1 = new uuid ('String to be hashed'); // Generates a new UUID v5 using '0000…' as the namespace

uuid::setDefaultNamespace ('87e1d1be-df8d-11e7-b804-0800276fa7d4');

$u2 = new uuid ('String to be hashed'); // Generates a new UUID v5 using '87e1…' as the namespace

抑制命名空间生成

如果 $namespace 参数是布尔值 false，则抑制命名空间生成。

在这种情况下，空的 $uuid 参数仍然会生成版本 4 UUID。

$u = new uuid ('', false); // Generates a new UUID v4

否则，将 $uuid 参数严格视为要导入的值。如果 $uuid 不为空，但也不是有效的 UUID，并且 $namespace 是布尔值 false，则抛出 InvalidString 或 InvalidBinary 异常（见下文）。

try
{
	$u = new uuid ('String to be hashed', false);
}
catch (InvalidString $e)
{
	echo $e->getMessage () . PHP_EOL;
}

工厂表示法

还有另一种工厂风格的表示法可供选择

$u1 = uuid::v4 (); // Generates a new UUID v4
$u2 = uuid::v5 ('String to be hashed'); // Generates a new UUID v5 using the default namespace
$u3 = uuid::v5 ('String to be hashed', '87e1d1be-df8d-11e7-b804-0800276fa7d4'); // Generates a new UUID v5 using '87e1…' as the namespace

工厂风格的表示法还可以访问版本 1 和 3 UUID；这些不能通过直接对象实例化来访问。

$u1 = uuid::v1 (); // Generates a new UUID v1
$u2 = uuid::v3 ('String to be hashed'); // Generates a new UUID v3 using the default namespace
$u3 = uuid::v3 ('String to be hashed', '87e1d1be-df8d-11e7-b804-0800276fa7d4'); // Generates a new UUID v3 using '87e1…' as the namespace

由于版本 1 UUID 依赖于 MAC 地址，而 PHP 没有可靠的平台无关方法来获取服务器的 MAC 地址，因此必须手动定义 MAC 地址。在脚本执行开始时，MAC 地址初始化为“nil”值，但可以随后将其设置为任何有效的 MAC 地址。

echo bin2hex (uuid::getMACAddress ()); // '000000000000'

uuid::setMACAddress ('01:23:45:67:89:AB');

输出格式

三种输出格式都作为只读属性提供。__toString 魔术方法返回长格式。

echo $u->long			. PHP_EOL;	// fae0b286-007f-3824-a616-16d7332b7a09
echo $u->short			. PHP_EOL;	// -uCyhgB_OCSmFhbXMyt6CQ
echo bin2hex ($u->binary)	. PHP_EOL;	// fae0b286007f3824a61616d7332b7a09
echo $u				. PHP_EOL;	// fae0b286-007f-3824-a616-16d7332b7a09

其他属性

UUID版本和变体也可以作为只读属性使用。

echo $u				. PHP_EOL;	// fae0b286-007f-3824-a616-16d7332b7a09
echo $u->version		. PHP_EOL;	// 3
echo $u->variant		. PHP_EOL;	// 1

异常

在正常操作过程中，可能会抛出以下异常

  • \Boondoc\uuid\InvalidBinary：指定的$uuid无法验证为UUID，且$namespace为false。自动通过bin2hex ()传递$name进行打印。
  • \Boondoc\uuid\InvalidString：指定的$uuid无法验证为UUID，且$namespace为false。捕获异常以包括InvalidBinary。
  • \Boondoc\uuid\InvalidNamespace：指定的$namespace无法验证为UUID。
  • \Boondoc\uuid\InvalidAddress：在调用::setMACAddress时，指定的$macaddress无法验证为MAC地址。
  • \Boondoc\uuid\Exception：抽象类型，永远不会显式抛出；捕获异常以包括上述所有。

这些异常仅用于捕获，并且不应该需要显式抛出。

上述所有异常都包含一个新方法，getValue ()，它返回不带消息字符串其余部分的有问题的值。

示例

<?php
	require ('props/autoload.php'); 		// Or 'vendor/autoload.php' if youʼre a traditionalist…

	use Boondoc\uuid;

	uuid::setDefaultNamespace ('0f1abe4a-df91-11e7-86fc-0800276fa7d4'); // See Note 1

	// Import; these all produce objects with identical internal values
	$uuid_long			= new uuid ('fae0b286-007f-3824-a616-16d7332b7a09');
	$uuid_caps			= new uuid ('FAE0B286-007F-3824-A616-16D7332B7A09');
	$uuid_guid			= new uuid ('{fae0b286-007f-3824-a616-16d7332b7a09}');
	$uuid_short			= new uuid ('-uCyhgB_OCSmFhbXMyt6CQ');
	$uuid_base64			= new uuid ('+uCyhgB/OCSmFhbXMyt6CQ==');
	$uuid_binary			= new uuid ("\xFA\xE0\xB2\x86\x00\x7F\x38\x24\xA6\x16\x16\xD7\x33\x2B\x7A\x09");
	$uuid_suppress_namespace	= new uuid ('fae0b286-007f-3824-a616-16d7332b7a09', false);

	// Instance generation
	$uuid_v4			= new uuid ();
	$uuid_v5_global_namespace	= new uuid ('String to be hashed'); // Namespace is '0f1a…'
	$uuid_v5_string_namespace	= new uuid ('String to be hashed', '87e1d1be-df8d-11e7-b804-0800276fa7d4');
	$uuid_v5_object_namespace	= new uuid ('String to be hashed', $uuid_v4);
	$uuid_v5_constant_namespace	= new uuid ('String to be hashed',  UUID_NAMESPACE_OID); // See Note 2

	// Factory generation
	$uuid_v1			= uuid::v1 ();
	$uuid_v3_global_namespace	= uuid::v3 ('String to be hashed'); // Namespace is '0f1a…'
	$uuid_v3_string_namespace	= uuid::v3 ('String to be hashed', '87e1d1be-df8d-11e7-b804-0800276fa7d4');
	$uuid_v3_object_namespace	= uuid::v3 ('String to be hashed', $uuid_v1);
	$uuid_v3_constant_namespace	= uuid::v3 ('String to be hashed',  UUID_NAMESPACE_OID); // See Note 2

	$uuid_v4			= uuid::v4 ();
	$uuid_v5_global_namespace	= uuid::v5 ('String to be hashed'); // Namespace is '0f1a…'
	$uuid_v5_string_namespace	= uuid::v5 ('String to be hashed', '87e1d1be-df8d-11e7-b804-0800276fa7d4');
	$uuid_v5_object_namespace	= uuid::v5 ('String to be hashed', $uuid_v4);
	$uuid_v5_constant_namespace	= uuid::v5 ('String to be hashed',  UUID_NAMESPACE_OID); // See Note 2

	// Output formats
	echo $uuid_long->long				. PHP_EOL;	// fae0b286-007f-3824-a616-16d7332b7a09
	echo $uuid_long->short				. PHP_EOL;	// -uCyhgB_OCSmFhbXMyt6CQ
	echo bin2hex ($uuid_long->binary)		. PHP_EOL;	// fae0b286007f3824a61616d7332b7a09
	echo $uuid_long 				. PHP_EOL;	// fae0b286-007f-3824-a616-16d7332b7a09

	// Validation
	uuid::isValidLong ('fae0b286-007f-3824-a616-16d7332b7a09');	// true
	uuid::isValidLong ('00000000-0000-0000-0000-000000000000');	// true: nil UUID
	uuid::isValidLong ('FAE0B286-007F-3824-A616-16D7332B7A09');	// true: uppercase is permitted on input
	uuid::isValidLong ('{fae0b286007f3824a61616d7332b7a09}');	// true: dashes and end-braces are both optional
	uuid::isValidLong ('fae0b286-007f-e824-a616-16d7332b7a09');	// false: there is no UUID version 'E'
	uuid::isValidLong ('fae0b286-007f-3824-c616-16d7332b7a09');	// false: variant 2 is not permitted (character 'c')
	uuid::isValidLong ('fae0b286-007f-j824-a616-16d7332b7a09');	// false: character 'j' is not permitted
	uuid::isValidLong ('fae0b286-007f-3824-a61616d7-332b7a09');	// false: dash in the wrong place
	uuid::isValidLong ('fae0b286-007f-3824-a616-16d7332b7a0936');	// false: wrong length

	uuid::isValidShort ('-uCyhgB_OCSmFhbXMyt6CQ');			// true
	uuid::isValidShort ('AAAAAAAAAAAAAAAAAAAAAA');			// true: nil UUID
	uuid::isValidShort ('+uCyhgB/OCSmFhbXMyt6CQ==');		// true: standard base64 charset is permitted on input, padding is optional
	uuid::isValidShort ('-uCyhgB_OCSmFhbXMyt6Cj');			// false: final character must be one of [g, w, A, Q]
	uuid::isValidShort ('-uCyhgB_OCSmFhbXMyt6CQm'); 		// false: wrong length

	uuid::isValidBinary ("\xFA\xE0\xB2\x86\x00\x7F\x38\x24\xA6\x16\x16\xD7\x33\x2B\x7A\x09");	// true
	uuid::isValidBinary ("\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00");	// true: nil UUID
	uuid::isValidBinary ("\xFA\xE0\xB2\x86\x00\x7F\xE8\x24\xA6\x16\x16\xD7\x33\x2B\x7A\x09");	// false: there is no UUID version 'E'
	uuid::isValidBinary ("\xFA\xE0\xB2\x86\x00\x7F\xE8\x24\xA6\x16\x16\xD7\x33\x2B\x7A\x09\x36");	// false: wrong length

	uuid::isValid ('fae0b286-007f-3824-a616-16d7332b7a09');		// true		// See Note 3
	uuid::isValid ($uuid_v4);					// true

注意

  1. 如果默认命名空间从未设置，则默认为“nil” UUID '00000000-0000-0000-0000-000000000000'。
  2. RFC 4122 附录C建议一些预定义的命名空间。该库定义的常量是
    • UUID_NAMESPACE_NIL ≈ '00000000-0000-0000-0000-000000000000'
    • UUID_NAMESPACE_DNS ≈ '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
    • UUID_NAMESPACE_URL ≈ '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
    • UUID_NAMESPACE_OID ≈ '6ba7b812-9dad-11d1-80b4-00c04fd430c8'
    • UUID_NAMESPACE_X500 ≈ '6ba7b814-9dad-11d1-80b4-00c04fd430c8' 注意，这些常量实际上是定义为Binary字符串的，当作为$uuid参数传递给namespaced UUID时会产生意外的结果。
  3. uuid::isValid ()如果参数是uuid对象，或者任何::isValidLong ()、::isValidShort ()或::isValidBinary ()会返回true，则返回true。