ramsey/uuid-doctrine

ramsey/uuid-doctrine bridges the popular ramsey/uuid library with Doctrine, letting you map UUID values directly onto entity fields as first-class Doctrine column types. Instead of storing and casting identifiers by hand, you register the package’s custom types and Doctrine transparently converts between database columns and Ramsey\Uuid\UuidInterface objects.

It ships several storage strategies, including a human-readable string uuid type, a compact uuid_binary type, and an uuid_binary_ordered_time type optimized for index locality, along with ID generators (including ordered-time and UUIDv7) so entities can produce UUID primary keys automatically.

What You Get

• A string uuid Doctrine type mapping to ramsey/uuid objects
• Compact uuid_binary and uuid_binary_ordered_time column types
• ID generators including ordered-time and UUIDv7 strategies
• Automatic conversion between database values and UuidInterface instances
• Compatibility with Doctrine DBAL 2, 3, and 4 and Doctrine ORM

Common Use Cases

• Using UUIDs as entity primary keys in Doctrine ORM
• Storing UUIDs compactly as binary columns for smaller indexes
• Improving index performance with ordered-time UUID storage
• Auto-generating UUID identifiers on entity persistence

Under The Hood

Architecture - The src/ directory contains a small set of focused classes: DBAL type implementations (UuidType, UuidBinaryType, UuidBinaryOrderedTimeType) that extend Doctrine’s type system to convert between database values and UuidInterface, and ID generators (UuidGenerator, UuidOrderedTimeGenerator, UuidV7Generator) that hook into Doctrine’s identifier generation. A GetBindingTypeImplementation helper smooths over binding-type differences across DBAL versions.

Tech Stack - PHP 8.1+ depending on doctrine/dbal (2.8, 3, or 4) and ramsey/uuid (3.9.7+ or 4), with Doctrine ORM as a dev/optional companion. It plugs into Doctrine’s existing type and generator extension points rather than introducing new infrastructure.

Code Quality - The project follows Ben Ramsey’s rigorous open-source tooling: PHPUnit tests with Codecov coverage, PHPStan static analysis, PHP_CodeSniffer, Captain Hook git hooks, and conventional-commit enforcement, all wired through CI. The codebase is small, well-typed, and mature.

API Design - Usage is declarative and idiomatic to Doctrine: register the types once, then annotate entity fields with the type name (e.g. uuid or uuid_binary_ordered_time) and optionally attach a generator. Because it leans on Doctrine’s own conventions and the thoroughly documented ramsey/uuid API, the learning curve is minimal for developers already using Doctrine.