ramsey/uuid-doctrine

将 ramsey/uuid 作为 Doctrine 字段类型使用。

维护者

详细信息

github.com/ramsey/uuid-doctrine

源代码

问题

资助包维护！
ramsey
Tidelift

安装次数: 29,307,905

依赖项: 226

建议者: 13

安全: 0

星标: 889

关注者: 18

分支: 84

开放问题: 8

2.1.0 2024-05-27 00:00 UTC

Requires

Requires (Dev)

MIT 491e1bfa4d9d81e52a60470fa92c871f7eef919e

databasedoctrineuuididentifierguid

This package is auto-updated.

Last update: 2024-08-26 16:42:21 UTC

README

使用 ramsey/uuid 作为 Doctrine 字段类型

Source Code Download Package PHP Programming Language Read License Build Status Codecov Code Coverage

ramsey/uuid-doctrine 包提供了使用 ramsey/uuid 作为 Doctrine 字段类型 的能力。

本项目遵守 行为准则。通过参与本项目及其社区，您应遵守此准则。

安装

使用 Composer 将此包作为依赖项安装。

composer require ramsey/uuid-doctrine

使用方法

配置

要配置 Doctrine 以使用 ramsey/uuid 作为字段类型，您需要在您的引导程序中设置以下内容：

\Doctrine\DBAL\Types\Type::addType('uuid', 'Ramsey\Uuid\Doctrine\UuidType');

在 Symfony 中

# config/packages/doctrine.yaml
doctrine:
    dbal:
        types:
            uuid: Ramsey\Uuid\Doctrine\UuidType

在 Zend Framework 中

<?php
// module.config.php
use Ramsey\Uuid\Doctrine\UuidType;

return [
    'doctrine' => [
        'configuration' => [
            'orm_default' => [
                'types' => [
                    UuidType::NAME => UuidType::class,

在 Laravel 中

<?php
// config/doctrine.php
    'custom_types'               => [
        \Ramsey\Uuid\Doctrine\UuidType::NAME => \Ramsey\Uuid\Doctrine\UuidType::class
    ],

在 roave/psr-container-doctrine 中

<?php
use Ramsey\Uuid\Doctrine\UuidType;

return [
    'doctrine' => [
        'types' => [
            UuidType::NAME => UuidType::class,
        ],
        /* ... */
    ],
    /* ... */
];

映射

然后，在您的模型中，您可以通过将 #[Column] 类型设置为 uuid 并定义一个自定义的 Ramsey\Uuid\UuidGenerator 生成器来注解属性。Doctrine 将处理其余部分。

use Doctrine\ORM\Mapping as ORM;
use Ramsey\Uuid\Doctrine\UuidGenerator;
use Ramsey\Uuid\UuidInterface;


#[ORM\Entity]
#[ORM\Table(name: "products")]
class Product
{
    #[ORM\Id]
    #[ORM\Column(type: "uuid", unique: true)]
    #[ORM\GeneratedValue(strategy: "CUSTOM")]
    #[ORM\CustomIdGenerator(class: UuidGenerator::class)]
    protected UuidInterface $id;

    public function getId(): UuidInterface
    {
        return $this->id;
    }
}

如果您使用的是 XML 映射而不是 PHP 属性。

<id name="id" column="id" type="uuid">
    <generator strategy="CUSTOM"/>
    <custom-id-generator class="Ramsey\Uuid\Doctrine\UuidGenerator"/>
</id>

您还可以使用 YAML 映射。

id:
    id:
        type: uuid
        generator:
            strategy: CUSTOM
        customIdGenerator:
            class: Ramsey\Uuid\Doctrine\UuidGenerator

二进制数据库列

在上一个示例中，如果使用 MariaDB / MySQL，Doctrine 将创建一个类型为 CHAR(36) 的数据库列，但您也可以使用此库将 UUID 存储为二进制字符串。UuidBinaryType 帮助实现这一点。

在您的引导程序中放置以下内容：

\Doctrine\DBAL\Types\Type::addType('uuid_binary', 'Ramsey\Uuid\Doctrine\UuidBinaryType');
$entityManager->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping('uuid_binary', 'binary');

在 Symfony 中

# config/packages/doctrine.yaml
doctrine:
    dbal:
        types:
            uuid_binary:  Ramsey\Uuid\Doctrine\UuidBinaryType
# Uncomment if using doctrine/orm <2.8
        # mapping_types:
            # uuid_binary: binary

然后，在注解模型类属性时，使用 uuid_binary 而不是 uuid

#[Column(type: "uuid_binary")]

InnoDB 优化的二进制 UUID - 已弃用

如果您想将 UUID 用作主键，则更合适。请注意，这可能会导致意外的效果，如果

  • 解码未使用此方法生成的字节
  • 另一个代码（不了解此方法）尝试解码生成的字节

更多信息请参阅此 Percona 文章 和 Ben Ramsey 的 UUID 讲座（从 第 58 页 开始）。

\Doctrine\DBAL\Types\Type::addType('uuid_binary_ordered_time', 'Ramsey\Uuid\Doctrine\UuidBinaryOrderedTimeType');
$entityManager->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping('uuid_binary_ordered_time', 'binary');

在 Symfony 中

# config/packages/doctrine.yaml
doctrine:
   dbal:
       types:
           uuid_binary_ordered_time: Ramsey\Uuid\Doctrine\UuidBinaryOrderedTimeType
# Uncomment if using doctrine/orm <2.8
       # mapping_types:
           # uuid_binary_ordered_time: binary

然后，在您的模型中，您可以通过将 @Column 类型设置为 uuid_binary_ordered_time 并定义一个自定义的 Ramsey\Uuid\UuidOrderedTimeGenerator 生成器来注解属性。Doctrine 将处理其余部分。

#[Entity]
#[Table(name: "products")]´
class Product
{
    #[Id]
    #[Column(type: "uuid_binary_ordered_time", unique: true)]
    #[GeneratedValue(strategy: "CUSTOM")]
    #[CustomIdGenerator(class: UuidOrderedTimeGenerator::class)]
    protected UuidInterface $id;

    public function getId(): UuidInterface
    {
        return $this->id;
    }
}

如果您使用的是 XML 映射而不是 PHP 注解。

<id name="id" column="id" type="uuid_binary_ordered_time">
    <generator strategy="CUSTOM"/>
    <custom-id-generator class="Ramsey\Uuid\Doctrine\UuidOrderedTimeGenerator"/>
</id>

InnoDB 优化的二进制 UUID - 新方法

随着新 UUID 类型（包括可排序、基于 Unix 纪元的 UUID 版本 7）的引入，现在建议使用常规 uuid_binary 与 Ramsey\Uuid\Doctrine\UuidV7Generator 用于主键。

在您的引导程序中放置以下内容：

\Doctrine\DBAL\Types\Type::addType('uuid_binary', 'Ramsey\Uuid\Doctrine\UuidBinaryType');
$entityManager->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping('uuid_binary', 'binary');

在 Symfony 中

# config/packages/doctrine.yaml
doctrine:
    dbal:
        types:
            uuid_binary:  Ramsey\Uuid\Doctrine\UuidBinaryType
# Uncomment if using doctrine/orm <2.8
        # mapping_types:
            # uuid_binary: binary

然后，在您的模型中，您可以通过将 #[Column] 类型设置为 uuid_binary 并定义一个自定义的 Ramsey\Uuid\UuidV7Generator 生成器来注解属性。Doctrine 将处理其余部分。

#[Entity]
#[Table(name: "products")]
class Product
{
    #[Id]
    #[Column(type: "uuid_binary", unique: true)]
    #[GeneratedValue(strategy: "CUSTOM")]
    #[CustomIdGenerator(class: UuidV7Generator::class)]
    protected UuidInterface $id;

    public function getId(): UuidInterface
    {
        return $this->id;
    }
}

如果您使用的是 XML 映射而不是 PHP 注解。

<id name="id" column="id" type="uuid_binary">
    <generator strategy="CUSTOM"/>
    <custom-id-generator class="Ramsey\Uuid\Doctrine\UuidV7Generator"/>
</id>

PostgreSQL 考虑因素

如果您正在使用 PostgreSQL，Doctrine 使用 PostgreSQL 的 uuid 为 Ramsey\Uuid\Doctrine\UuidType (uuid)。因此，当使用 PostgreSQL 时，您不需要使用 uuid_binary / uuid_binary_ordered_time 类型。不过，您仍然可以使用 UuidV7Generator::class 来优化索引。

#[Entity]
#[Table(name: "products")]
class Product
{
    #[Id]
    #[Column(type: "uuid", unique: true)]
    #[GeneratedValue(strategy: "CUSTOM")]
    #[CustomIdGenerator(class: UuidV7Generator::class)]
    protected UuidInterface $id;

    public function getId(): UuidInterface
    {
        return $this->id;
    }
}

处理二进制标识符

当处理二进制标识符时，您可能希望将它们转换为可读的格式。从 MySql 8.0 开始，您可以使用文档中记录的 BIN_TO_UUID 和 UUID_TO_BIN 函数这里。第二个参数确定是否需要交换字节顺序，因此当使用 uuid_binary 时，您应传递 0；当使用 uuid_binary_ordered_time 时，您应传递 1。

对于其他版本，您可以使用以下方法

DELIMITER $$

CREATE
    FUNCTION BIN_TO_UUID(bin_uuid BINARY(16), swap_flag BOOLEAN)
    RETURNS CHAR(36)
    DETERMINISTIC
    BEGIN
       DECLARE hex_uuid CHAR(32);
       SET hex_uuid = HEX(bin_uuid);
       RETURN LOWER(CONCAT(
            IF(swap_flag, SUBSTR(hex_uuid, 9, 8),SUBSTR(hex_uuid, 1, 8)), '-',
            IF(swap_flag, SUBSTR(hex_uuid, 5, 4),SUBSTR(hex_uuid, 9, 4)), '-',
            IF(swap_flag, SUBSTR(hex_uuid, 1, 4),SUBSTR(hex_uuid, 13, 4)), '-',
            SUBSTR(hex_uuid, 17, 4), '-',
            SUBSTR(hex_uuid, 21)
        ));
    END$$


CREATE
    FUNCTION UUID_TO_BIN(str_uuid CHAR(36), swap_flag BOOLEAN)
    RETURNS BINARY(16)
    DETERMINISTIC
    BEGIN
      RETURN UNHEX(CONCAT(
          IF(swap_flag, SUBSTR(str_uuid, 15, 4),SUBSTR(str_uuid, 1, 8)),
          SUBSTR(str_uuid, 10, 4),
          IF(swap_flag, SUBSTR(str_uuid, 1, 8),SUBSTR(str_uuid, 15, 4)),
          SUBSTR(str_uuid, 20, 4),
          SUBSTR(str_uuid, 25))
      );
    END$$

DELIMITER ;

测试

mysql> select '07a2f327-103a-11e9-8025-00ff5d11a779' as uuid, BIN_TO_UUID(UUID_TO_BIN('07a2f327-103a-11e9-8025-00ff5d11a779', 0), 0) as flip_flop;
+--------------------------------------+--------------------------------------+
| uuid                                 | flip_flop                            |
+--------------------------------------+--------------------------------------+
| 07a2f327-103a-11e9-8025-00ff5d11a779 | 07a2f327-103a-11e9-8025-00ff5d11a779 |
+--------------------------------------+--------------------------------------+
1 row in set (0.00 sec)

mysql> select '07a2f327-103a-11e9-8025-00ff5d11a779' as uuid, BIN_TO_UUID(UUID_TO_BIN('07a2f327-103a-11e9-8025-00ff5d11a779', 1), 1) as flip_flop;
+--------------------------------------+--------------------------------------+
| uuid                                 | flip_flop                            |
+--------------------------------------+--------------------------------------+
| 07a2f327-103a-11e9-8025-00ff5d11a779 | 07a2f327-103a-11e9-8025-00ff5d11a779 |
+--------------------------------------+--------------------------------------+
1 row in set (0.00 sec)

更多信息

有关使用 Doctrine 的更多信息，请查看 "使用 Doctrine 入门" 教程。

贡献

欢迎贡献！要贡献，请熟悉 CONTRIBUTING.md。

协调披露

保护用户信息的安全和保密是首要任务，我们欢迎外部安全研究人员的贡献。如果您认为您已发现本存储库维护的软件中的安全问题，请阅读 SECURITY.md 了解提交漏洞报告的说明。

ramsey/uuid-doctrine for 企业

作为 Tidelift 订阅的一部分提供。

ramsey/uuid-doctrine 的维护者以及成千上万的其他包的维护者正在与 Tidelift 合作，为构建应用程序使用的开源包提供商业支持和维护。节省时间，降低风险，提高代码质量，同时支付您使用的确切包的维护者。 了解更多。

版权和许可

ramsey/uuid-doctrine 库版权 © Ben Ramsey，许可协议为 MIT 许可证 (MIT)。有关更多信息，请参阅 LICENSE。