ramsey / uuid-doctrine
Use ramsey/uuid as a Doctrine field type.
Installs: 30 801 301
Dependents: 228
Suggesters: 13
Security: 0
Stars: 898
Watchers: 18
Forks: 84
Open Issues: 10
Requires
- php: ^8.1
- doctrine/dbal: ^2.8 || ^3.0 || ^4.0
- ramsey/uuid: ^3.9.7 || ^4.0
Requires (Dev)
- captainhook/plugin-composer: ^5.3
- doctrine/orm: ^2.5 || ^3.0
- ergebnis/composer-normalize: ^2.28.3
- mockery/mockery: ^1.5
- php-parallel-lint/php-console-highlighter: ^1.0
- php-parallel-lint/php-parallel-lint: ^1.3
- phpcsstandards/phpcsutils: ^1.0.0-alpha4
- phpstan/extension-installer: ^1.2
- phpstan/phpstan: ^1.9
- phpstan/phpstan-mockery: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- phpunit/phpunit: ^10.5
- ramsey/coding-standard: ^2.0.3
- ramsey/conventional-commits: ^1.3
README
Use ramsey/uuid as a Doctrine field type
The ramsey/uuid-doctrine package provides the ability to use ramsey/uuid as a Doctrine field type.
This project adheres to a code of conduct. By participating in this project and its community, you are expected to uphold this code.
Installation
Install this package as a dependency using Composer.
composer require ramsey/uuid-doctrine
Usage
Configuration
To configure Doctrine to use ramsey/uuid as a field type, you'll need to set up the following in your bootstrap:
\Doctrine\DBAL\Types\Type::addType('uuid', 'Ramsey\Uuid\Doctrine\UuidType');
In Symfony:
# config/packages/doctrine.yaml doctrine: dbal: types: uuid: Ramsey\Uuid\Doctrine\UuidType
In Zend Framework:
<?php // module.config.php use Ramsey\Uuid\Doctrine\UuidType; return [ 'doctrine' => [ 'configuration' => [ 'orm_default' => [ 'types' => [ UuidType::NAME => UuidType::class,
In Laravel:
<?php // config/doctrine.php 'custom_types' => [ \Ramsey\Uuid\Doctrine\UuidType::NAME => \Ramsey\Uuid\Doctrine\UuidType::class ],
In roave/psr-container-doctrine:
<?php use Ramsey\Uuid\Doctrine\UuidType; return [ 'doctrine' => [ 'types' => [ UuidType::NAME => UuidType::class, ], /* ... */ ], /* ... */ ];
Mappings
Then, in your models, you may annotate properties by setting the #[Column]
type to uuid
, and defining a custom generator of Ramsey\Uuid\UuidGenerator
.
Doctrine will handle the rest.
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; } }
If you use the XML Mapping instead of PHP attributes.
<id name="id" column="id" type="uuid"> <generator strategy="CUSTOM"/> <custom-id-generator class="Ramsey\Uuid\Doctrine\UuidGenerator"/> </id>
You can also use the YAML Mapping.
id: id: type: uuid generator: strategy: CUSTOM customIdGenerator: class: Ramsey\Uuid\Doctrine\UuidGenerator
Binary database columns
In the previous example, Doctrine will create a database column of type CHAR(36)
if MariaDB / MySQL are in use,
but you may also use this library to store UUIDs as binary strings. The
UuidBinaryType
helps accomplish this.
In your bootstrap, place the following:
\Doctrine\DBAL\Types\Type::addType('uuid_binary', 'Ramsey\Uuid\Doctrine\UuidBinaryType'); $entityManager->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping('uuid_binary', 'binary');
In 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
Then, when annotating model class properties, use uuid_binary
instead of uuid
:
#[Column(type: "uuid_binary")]
InnoDB-optimised binary UUIDs - deprecated
More suitable if you want to use UUIDs as primary key. Note that this can cause unintended effects if:
- decoding bytes that were not generated using this method
- another code (that isn't aware of this method) attempts to decode the resulting bytes
More information in this Percona article and UUID Talk by Ben Ramsey (starts at slide 58).
\Doctrine\DBAL\Types\Type::addType('uuid_binary_ordered_time', 'Ramsey\Uuid\Doctrine\UuidBinaryOrderedTimeType'); $entityManager->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping('uuid_binary_ordered_time', 'binary');
In 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
Then, in your models, you may annotate properties by setting the @Column
type to uuid_binary_ordered_time
, and defining a custom generator of
Ramsey\Uuid\UuidOrderedTimeGenerator
. Doctrine will handle the rest.
#[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; } }
If you use the XML Mapping instead of PHP annotations.
<id name="id" column="id" type="uuid_binary_ordered_time"> <generator strategy="CUSTOM"/> <custom-id-generator class="Ramsey\Uuid\Doctrine\UuidOrderedTimeGenerator"/> </id>
InnoDB-optimised binary UUIDs - new way
With the introduction of new
UUID types
(including sortable, unix epoch based UUID version 7) it is now recommended
to use regular uuid_binary
with Ramsey\Uuid\Doctrine\UuidV7Generator
for primary keys.
In your bootstrap, place the following:
\Doctrine\DBAL\Types\Type::addType('uuid_binary', 'Ramsey\Uuid\Doctrine\UuidBinaryType'); $entityManager->getConnection()->getDatabasePlatform()->registerDoctrineTypeMapping('uuid_binary', 'binary');
In 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
Then, in your models, you may annotate properties by setting the #[Column]
type to uuid_binary
, and defining a custom generator of
Ramsey\Uuid\UuidV7Generator
. Doctrine will handle the rest.
#[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; } }
If you use the XML Mapping instead of PHP annotations.
<id name="id" column="id" type="uuid_binary"> <generator strategy="CUSTOM"/> <custom-id-generator class="Ramsey\Uuid\Doctrine\UuidV7Generator"/> </id>
PostgreSQL considerations
If you are using PostgreSQL, Doctrine uses PostgreSQL's uuid
for the Ramsey\Uuid\Doctrine\UuidType
(uuid
).
Therefor you don't need to use the uuid_binary
/ uuid_binary_ordered_time
types when using PostgreSQL.
You can still use UuidV7Generator::class
to optimize indexing though.
#[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; } }
Working with binary identifiers
When working with binary identifiers you may wish to convert them into a readable format.
As of MySql 8.0 you can use the BIN_TO_UUID and UUID_TO_BIN functions documented here.
The second argument determines if the byte order should be swapped, therefore when using uuid_binary
you should pass 0
and when using uuid_binary_ordered_time
you should pass 1.
For other versions you can use the following:
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 ;
Tests:
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)
More information
For more information on getting started with Doctrine, check out the "Getting Started with Doctrine" tutorial.
Contributing
Contributions are welcome! To contribute, please familiarize yourself with CONTRIBUTING.md.
Coordinated Disclosure
Keeping user information safe and secure is a top priority, and we welcome the contribution of external security researchers. If you believe you've found a security issue in software that is maintained in this repository, please read SECURITY.md for instructions on submitting a vulnerability report.
ramsey/uuid-doctrine for enterprise
Available as part of the Tidelift Subscription.
The maintainers of ramsey/uuid-doctrine and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. Learn more.
Copyright and License
The ramsey/uuid-doctrine library is copyright © Ben Ramsey and licensed for use under the MIT License (MIT). Please see LICENSE for more information.