{"id":15024802,"url":"https://github.com/ramsey/uuid-doctrine","last_synced_at":"2025-05-14T08:06:33.786Z","repository":{"id":34049513,"uuid":"37828623","full_name":"ramsey/uuid-doctrine","owner":"ramsey","description":":snowflake::file_cabinet: Allow the use of a ramsey/uuid UUID as Doctrine field type.","archived":false,"fork":false,"pushed_at":"2024-08-26T16:42:17.000Z","size":277,"stargazers_count":897,"open_issues_count":9,"forks_count":85,"subscribers_count":18,"default_branch":"main","last_synced_at":"2024-10-29T15:11:41.925Z","etag":null,"topics":["dbal","doctrine","guid","identifiers","php","php7","php8","uuid"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ramsey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ramsey","tidelift":"packagist/ramsey/uuid-doctrine"}},"created_at":"2015-06-21T22:28:08.000Z","updated_at":"2024-10-24T18:58:22.000Z","dependencies_parsed_at":"2023-02-19T09:46:40.237Z","dependency_job_id":"39419ee1-8073-4948-8f0f-dd8dde0ecc8d","html_url":"https://github.com/ramsey/uuid-doctrine","commit_stats":{"total_commits":187,"total_committers":47,"mean_commits":3.978723404255319,"dds":"0.47593582887700536","last_synced_commit":"115f962fa16b80631354163bcbb818d8b880a968"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Fuuid-doctrine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Fuuid-doctrine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Fuuid-doctrine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Fuuid-doctrine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramsey","download_url":"https://codeload.github.com/ramsey/uuid-doctrine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101616,"owners_count":22014909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dbal","doctrine","guid","identifiers","php","php7","php8","uuid"],"created_at":"2024-09-24T20:00:59.676Z","updated_at":"2025-05-14T08:06:28.733Z","avatar_url":"https://github.com/ramsey.png","language":"PHP","funding_links":["https://github.com/sponsors/ramsey","https://tidelift.com/funding/github/packagist/ramsey/uuid-doctrine","https://tidelift.com/subscription/pkg/packagist-ramsey-uuid-doctrine?utm_source=packagist-ramsey-uuid-doctrine\u0026utm_medium=referral\u0026utm_campaign=enterprise\u0026utm_term=repo"],"categories":["Related Projects"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eramsey/uuid-doctrine\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cstrong\u003eUse \u003ca href=\"https://github.com/ramsey/uuid\"\u003eramsey/uuid\u003c/a\u003e as a \u003ca href=\"https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/types.html\"\u003eDoctrine field type\u003c/a\u003e\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/ramsey/uuid-doctrine\"\u003e\u003cimg src=\"http://img.shields.io/badge/source-ramsey/uuid--doctrine-blue.svg?style=flat-square\" alt=\"Source Code\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/ramsey/uuid-doctrine\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/ramsey/uuid-doctrine.svg?style=flat-square\u0026label=release\" alt=\"Download Package\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://php.net\"\u003e\u003cimg src=\"https://img.shields.io/packagist/php-v/ramsey/uuid-doctrine.svg?style=flat-square\u0026colorB=%238892BF\" alt=\"PHP Programming Language\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ramsey/uuid-doctrine/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/ramsey/uuid-doctrine.svg?style=flat-square\u0026colorB=darkcyan\" alt=\"Read License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ramsey/uuid-doctrine/actions/workflows/continuous-integration.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ramsey/uuid-doctrine/continuous-integration.yml?branch=main\u0026logo=github\u0026style=flat-square\" alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/ramsey/uuid-doctrine\"\u003e\u003cimg src=\"https://img.shields.io/codecov/c/gh/ramsey/uuid-doctrine?label=codecov\u0026logo=codecov\u0026style=flat-square\" alt=\"Codecov Code Coverage\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nThe ramsey/uuid-doctrine package provides the ability to use\n[ramsey/uuid][ramsey-uuid] as a [Doctrine field type][doctrine-field-type].\n\nThis project adheres to a [code of conduct](CODE_OF_CONDUCT.md).\nBy participating in this project and its community, you are expected to\nuphold this code.\n\n## Installation\n\nInstall this package as a dependency using [Composer](https://getcomposer.org).\n\n``` bash\ncomposer require ramsey/uuid-doctrine\n```\n\n## Usage\n\n### Configuration\n\nTo configure Doctrine to use ramsey/uuid as a field type, you'll need to set up\nthe following in your bootstrap:\n\n``` php\n\\Doctrine\\DBAL\\Types\\Type::addType('uuid', 'Ramsey\\Uuid\\Doctrine\\UuidType');\n```\n\nIn Symfony:\n\n``` yaml\n# config/packages/doctrine.yaml\ndoctrine:\n    dbal:\n        types:\n            uuid: Ramsey\\Uuid\\Doctrine\\UuidType\n```\n\nIn Zend Framework:\n\n```php\n\u003c?php\n// module.config.php\nuse Ramsey\\Uuid\\Doctrine\\UuidType;\n\nreturn [\n    'doctrine' =\u003e [\n        'configuration' =\u003e [\n            'orm_default' =\u003e [\n                'types' =\u003e [\n                    UuidType::NAME =\u003e UuidType::class,\n```\n\nIn Laravel:\n\n```php\n\u003c?php\n// config/doctrine.php\n    'custom_types'               =\u003e [\n        \\Ramsey\\Uuid\\Doctrine\\UuidType::NAME =\u003e \\Ramsey\\Uuid\\Doctrine\\UuidType::class\n    ],\n```\n\nIn [roave/psr-container-doctrine](https://github.com/Roave/psr-container-doctrine):\n\n```php\n\u003c?php\nuse Ramsey\\Uuid\\Doctrine\\UuidType;\n\nreturn [\n    'doctrine' =\u003e [\n        'types' =\u003e [\n            UuidType::NAME =\u003e UuidType::class,\n        ],\n        /* ... */\n    ],\n    /* ... */\n];\n```\n\n### Mappings\n\nThen, in your models, you may annotate properties by setting the `#[Column]`\ntype to `uuid`, and defining a custom generator of `Ramsey\\Uuid\\UuidGenerator`.\nDoctrine will handle the rest.\n\n``` php\nuse Doctrine\\ORM\\Mapping as ORM;\nuse Ramsey\\Uuid\\Doctrine\\UuidGenerator;\nuse Ramsey\\Uuid\\UuidInterface;\n\n\n#[ORM\\Entity]\n#[ORM\\Table(name: \"products\")]\nclass Product\n{\n    #[ORM\\Id]\n    #[ORM\\Column(type: \"uuid\", unique: true)]\n    #[ORM\\GeneratedValue(strategy: \"CUSTOM\")]\n    #[ORM\\CustomIdGenerator(class: UuidGenerator::class)]\n    protected UuidInterface $id;\n\n    public function getId(): UuidInterface\n    {\n        return $this-\u003eid;\n    }\n}\n```\n\nIf you use the XML Mapping instead of PHP attributes.\n\n``` xml\n\u003cid name=\"id\" column=\"id\" type=\"uuid\"\u003e\n    \u003cgenerator strategy=\"CUSTOM\"/\u003e\n    \u003ccustom-id-generator class=\"Ramsey\\Uuid\\Doctrine\\UuidGenerator\"/\u003e\n\u003c/id\u003e\n```\n\nYou can also use the YAML Mapping.\n\n``` yaml\nid:\n    id:\n        type: uuid\n        generator:\n            strategy: CUSTOM\n        customIdGenerator:\n            class: Ramsey\\Uuid\\Doctrine\\UuidGenerator\n```\n\n### Binary database columns\n\nIn the previous example, Doctrine will create a database column of type `CHAR(36)` if MariaDB / MySQL are in use,\nbut you may also use this library to store UUIDs as binary strings. The\n`UuidBinaryType` helps accomplish this.\n\nIn your bootstrap, place the following:\n\n``` php\n\\Doctrine\\DBAL\\Types\\Type::addType('uuid_binary', 'Ramsey\\Uuid\\Doctrine\\UuidBinaryType');\n$entityManager-\u003egetConnection()-\u003egetDatabasePlatform()-\u003eregisterDoctrineTypeMapping('uuid_binary', 'binary');\n```\n\nIn Symfony:\n\n``` yaml\n# config/packages/doctrine.yaml\ndoctrine:\n    dbal:\n        types:\n            uuid_binary:  Ramsey\\Uuid\\Doctrine\\UuidBinaryType\n# Uncomment if using doctrine/orm \u003c2.8\n        # mapping_types:\n            # uuid_binary: binary\n```\n\nThen, when annotating model class properties, use `uuid_binary` instead of `uuid`:\n\n    #[Column(type: \"uuid_binary\")]\n\n### InnoDB-optimised binary UUIDs - deprecated\n\nMore suitable if you want to use UUIDs as primary key. Note that this can cause\nunintended effects if:\n\n* decoding bytes that were not generated using this method\n* another code (that isn't aware of this method) attempts to decode the\n  resulting bytes\n\nMore information in this [Percona article][percona-optimized-uuids]\nand [UUID Talk by Ben Ramsey][benramsey-com-uuid-talk] (starts at [slide 58][]).\n\n``` php\n\\Doctrine\\DBAL\\Types\\Type::addType('uuid_binary_ordered_time', 'Ramsey\\Uuid\\Doctrine\\UuidBinaryOrderedTimeType');\n$entityManager-\u003egetConnection()-\u003egetDatabasePlatform()-\u003eregisterDoctrineTypeMapping('uuid_binary_ordered_time', 'binary');\n```\n\nIn Symfony:\n\n ``` yaml\n# config/packages/doctrine.yaml\ndoctrine:\n    dbal:\n        types:\n            uuid_binary_ordered_time: Ramsey\\Uuid\\Doctrine\\UuidBinaryOrderedTimeType\n# Uncomment if using doctrine/orm \u003c2.8\n        # mapping_types:\n            # uuid_binary_ordered_time: binary\n```\n\nThen, in your models, you may annotate properties by setting the `@Column`\ntype to `uuid_binary_ordered_time`, and defining a custom generator of\n`Ramsey\\Uuid\\UuidOrderedTimeGenerator`. Doctrine will handle the rest.\n\n``` php\n#[Entity]\n#[Table(name: \"products\")]´\nclass Product\n{\n    #[Id]\n    #[Column(type: \"uuid_binary_ordered_time\", unique: true)]\n    #[GeneratedValue(strategy: \"CUSTOM\")]\n    #[CustomIdGenerator(class: UuidOrderedTimeGenerator::class)]\n    protected UuidInterface $id;\n\n    public function getId(): UuidInterface\n    {\n        return $this-\u003eid;\n    }\n}\n```\n\nIf you use the XML Mapping instead of PHP annotations.\n\n``` xml\n\u003cid name=\"id\" column=\"id\" type=\"uuid_binary_ordered_time\"\u003e\n    \u003cgenerator strategy=\"CUSTOM\"/\u003e\n    \u003ccustom-id-generator class=\"Ramsey\\Uuid\\Doctrine\\UuidOrderedTimeGenerator\"/\u003e\n\u003c/id\u003e\n```\n\n### InnoDB-optimised binary UUIDs - new way\n\nWith the introduction of new\n[UUID types](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html)\n(including sortable, unix epoch based UUID version 7) it is now recommended\nto use regular `uuid_binary` with `Ramsey\\Uuid\\Doctrine\\UuidV7Generator` for primary keys.\n\nIn your bootstrap, place the following:\n\n``` php\n\\Doctrine\\DBAL\\Types\\Type::addType('uuid_binary', 'Ramsey\\Uuid\\Doctrine\\UuidBinaryType');\n$entityManager-\u003egetConnection()-\u003egetDatabasePlatform()-\u003eregisterDoctrineTypeMapping('uuid_binary', 'binary');\n```\n\nIn Symfony:\n\n``` yaml\n# config/packages/doctrine.yaml\ndoctrine:\n    dbal:\n        types:\n            uuid_binary:  Ramsey\\Uuid\\Doctrine\\UuidBinaryType\n# Uncomment if using doctrine/orm \u003c2.8\n        # mapping_types:\n            # uuid_binary: binary\n```\n\nThen, in your models, you may annotate properties by setting the `#[Column]`\ntype to `uuid_binary`, and defining a custom generator of\n`Ramsey\\Uuid\\UuidV7Generator`. Doctrine will handle the rest.\n\n``` php\n#[Entity]\n#[Table(name: \"products\")]\nclass Product\n{\n    #[Id]\n    #[Column(type: \"uuid_binary\", unique: true)]\n    #[GeneratedValue(strategy: \"CUSTOM\")]\n    #[CustomIdGenerator(class: UuidV7Generator::class)]\n    protected UuidInterface $id;\n\n    public function getId(): UuidInterface\n    {\n        return $this-\u003eid;\n    }\n}\n```\n\nIf you use the XML Mapping instead of PHP annotations.\n\n``` xml\n\u003cid name=\"id\" column=\"id\" type=\"uuid_binary\"\u003e\n    \u003cgenerator strategy=\"CUSTOM\"/\u003e\n    \u003ccustom-id-generator class=\"Ramsey\\Uuid\\Doctrine\\UuidV7Generator\"/\u003e\n\u003c/id\u003e\n```\n\n### PostgreSQL considerations\n\n\nIf you are using PostgreSQL, Doctrine uses PostgreSQL's `uuid` for the `Ramsey\\Uuid\\Doctrine\\UuidType` (`uuid`).\nTherefor you don't need to use the `uuid_binary` / `uuid_binary_ordered_time` types when using PostgreSQL.\nYou can still use `UuidV7Generator::class` to optimize indexing though.\n\n``` php\n#[Entity]\n#[Table(name: \"products\")]\nclass Product\n{\n    #[Id]\n    #[Column(type: \"uuid\", unique: true)]\n    #[GeneratedValue(strategy: \"CUSTOM\")]\n    #[CustomIdGenerator(class: UuidV7Generator::class)]\n    protected UuidInterface $id;\n\n    public function getId(): UuidInterface\n    {\n        return $this-\u003eid;\n    }\n}\n```\n\n### Working with binary identifiers\n\nWhen working with binary identifiers you may wish to convert them into a readable format.\nAs of MySql 8.0 you can use the BIN_TO_UUID and UUID_TO_BIN functions documented [here](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html).\nThe second argument determines if the byte order should be swapped, therefore when using ```uuid_binary``` you should pass 0\nand when using ```uuid_binary_ordered_time``` you should pass 1.\n\nFor other versions you can use the following:\n\n``` sql\nDELIMITER $$\n\nCREATE\n    FUNCTION BIN_TO_UUID(bin_uuid BINARY(16), swap_flag BOOLEAN)\n    RETURNS CHAR(36)\n    DETERMINISTIC\n    BEGIN\n       DECLARE hex_uuid CHAR(32);\n       SET hex_uuid = HEX(bin_uuid);\n       RETURN LOWER(CONCAT(\n            IF(swap_flag, SUBSTR(hex_uuid, 9, 8),SUBSTR(hex_uuid, 1, 8)), '-',\n            IF(swap_flag, SUBSTR(hex_uuid, 5, 4),SUBSTR(hex_uuid, 9, 4)), '-',\n            IF(swap_flag, SUBSTR(hex_uuid, 1, 4),SUBSTR(hex_uuid, 13, 4)), '-',\n            SUBSTR(hex_uuid, 17, 4), '-',\n            SUBSTR(hex_uuid, 21)\n        ));\n    END$$\n\n\nCREATE\n    FUNCTION UUID_TO_BIN(str_uuid CHAR(36), swap_flag BOOLEAN)\n    RETURNS BINARY(16)\n    DETERMINISTIC\n    BEGIN\n      RETURN UNHEX(CONCAT(\n          IF(swap_flag, SUBSTR(str_uuid, 15, 4),SUBSTR(str_uuid, 1, 8)),\n          SUBSTR(str_uuid, 10, 4),\n          IF(swap_flag, SUBSTR(str_uuid, 1, 8),SUBSTR(str_uuid, 15, 4)),\n          SUBSTR(str_uuid, 20, 4),\n          SUBSTR(str_uuid, 25))\n      );\n    END$$\n\nDELIMITER ;\n```\n\nTests:\n\n```\nmysql\u003e select '07a2f327-103a-11e9-8025-00ff5d11a779' as uuid, BIN_TO_UUID(UUID_TO_BIN('07a2f327-103a-11e9-8025-00ff5d11a779', 0), 0) as flip_flop;\n+--------------------------------------+--------------------------------------+\n| uuid                                 | flip_flop                            |\n+--------------------------------------+--------------------------------------+\n| 07a2f327-103a-11e9-8025-00ff5d11a779 | 07a2f327-103a-11e9-8025-00ff5d11a779 |\n+--------------------------------------+--------------------------------------+\n1 row in set (0.00 sec)\n\nmysql\u003e select '07a2f327-103a-11e9-8025-00ff5d11a779' as uuid, BIN_TO_UUID(UUID_TO_BIN('07a2f327-103a-11e9-8025-00ff5d11a779', 1), 1) as flip_flop;\n+--------------------------------------+--------------------------------------+\n| uuid                                 | flip_flop                            |\n+--------------------------------------+--------------------------------------+\n| 07a2f327-103a-11e9-8025-00ff5d11a779 | 07a2f327-103a-11e9-8025-00ff5d11a779 |\n+--------------------------------------+--------------------------------------+\n1 row in set (0.00 sec)\n```\n\n### More information\n\nFor more information on getting started with Doctrine, check out the \"[Getting\nStarted with Doctrine][doctrine-getting-started]\" tutorial.\n\n## Contributing\n\nContributions are welcome! To contribute, please familiarize yourself with\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Coordinated Disclosure\n\nKeeping user information safe and secure is a top priority, and we welcome the\ncontribution of external security researchers. If you believe you've found a\nsecurity issue in software that is maintained in this repository, please read\n[SECURITY.md][] for instructions on submitting a vulnerability report.\n\n## ramsey/uuid-doctrine for enterprise\n\nAvailable as part of the Tidelift Subscription.\n\nThe maintainers of ramsey/uuid-doctrine and thousands of other packages are\nworking with Tidelift to deliver commercial support and maintenance for the open\nsource packages you use to build your applications. Save time, reduce risk, and\nimprove code health, while paying the maintainers of the exact packages you use.\n[Learn more.](https://tidelift.com/subscription/pkg/packagist-ramsey-uuid-doctrine?utm_source=packagist-ramsey-uuid-doctrine\u0026utm_medium=referral\u0026utm_campaign=enterprise\u0026utm_term=repo)\n\n## Copyright and License\n\nThe ramsey/uuid-doctrine library is copyright © [Ben Ramsey](https://benramsey.com/) and\nlicensed for use under the MIT License (MIT). Please see [LICENSE](LICENSE) for more\ninformation.\n\n[percona-optimized-uuids]: https://www.percona.com/blog/2014/12/19/store-uuid-optimized-way/\n[benramsey-com-uuid-talk]: https://benramsey.com/talks/2016/11/tnphp-uuid/\n[ramsey-uuid]: https://github.com/ramsey/uuid\n[doctrine-field-type]: https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/types.html\n[doctrine-getting-started]: https://www.doctrine-project.org/projects/doctrine-orm/en/current/tutorials/getting-started.html\n[slide 58]: https://speakerdeck.com/ramsey/identify-all-the-things-with-uuids-true-north-php-2016?slide=58\n[security.md]: https://github.com/ramsey/uuid-doctrine/blob/main/SECURITY.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsey%2Fuuid-doctrine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framsey%2Fuuid-doctrine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsey%2Fuuid-doctrine/lists"}