Download the PHP package pixelfederation/doctrine-generic-types-bundle without Composer

PixelFederation DoctrineGenericTypesBundle

Installation

Install via Composer:

Register the bundle in config/bundles.php if you don't use Symfony Flex:

Configure the value hierarchy, its Doctrine type, and the directory containing concrete values:

Usage

Create a value object:

Use its concrete class as the Doctrine column type:

Doctrine now persists and hydrates FirstName automatically. Add mappings only for the value families used by the application; the complete list is below.

String-based generic types require an explicit column length because Doctrine ORM only provides the default length for its built-in string type.

Built-in value types

The bundle provides these base value classes and matching Doctrine types:

BigIntegerValue accepts integers and signed decimal integer strings so that values outside PHP's integer range remain exact. DecimalValue accepts numeric strings to avoid floating-point precision loss. Decimal entity fields must declare their precision and scale, for example #[ORM\Column(type: Price::class, precision: 10, scale: 2)]. AsciiStringValue rejects non-ASCII characters and, like StringValue, requires an explicit column length. TimeValue represents a time of day without a date or timezone; DBAL hydrates its DateTimeImmutable value with 1970-01-01 as the date. DateIntervalValue delegates Doctrine's portable ISO-8601 interval representation to the native DBAL dateinterval type.

JSON values

Two JSON value bases are available. JsonSerializableValue is intended for structured value objects. It requires the concrete value to implement jsonSerialize() and fromDbValue(), making both serialization and hydration explicit:

NativeJsonValue stores any value accepted by Doctrine DBAL's JSON type. Doctrine serializes the value with json_encode() and decodes JSON objects into associative arrays when loading them. This is convenient for native arrays and scalar JSON values, but applications are responsible for ensuring that the value is JSON-serializable.

Configure each hierarchy with its corresponding Doctrine type:

Serializer bridges

Serializer bridges persist the complete value object as JSON and deserialize the stored JSON directly back into its concrete value class. Unlike JsonSerializableValue, the value object does not implement its own serialization or hydration methods; serializer metadata and configuration control both directions.

Symfony Serializer

Install and configure Symfony Serializer in the application. The Serializer Pack includes the normalizers and supporting components commonly needed for object hydration:

Implement SymfonySerializerValue:

Map the hierarchy to SymfonySerializerValueType:

The service option is required when the Symfony bridge is enabled and may reference the standard serializer service or a dedicated serializer service. The bundle registers SymfonySerializerGenericTypeFactory with that service and creates one Doctrine type instance for each discovered concrete SymfonySerializerValue class.

JMS Serializer

Install and enable JMSSerializerBundle so that the application container exposes the jms_serializer service:

Implement JmsSerializerValue and add any JMS metadata required by the value object:

Map the hierarchy to JmsSerializerValueType:

The service option is required when the JMS bridge is enabled. It normally references the jms_serializer service provided by JMSSerializerBundle, but it may reference any service implementing JMS SerializerInterface.

Both bridges use the generic type factory mechanism. GenericTypeFactoryProvider receives all services tagged with GenericTypeFactoryProvider::TAG and selects the first supporting factory in priority order. The built-in StaticGenericTypeFactory remains responsible for types implementing StaticGenericType. Serializer types implement only the GenericType marker because their factories construct them with dependencies from the service container.

Neither bridge is enabled by merely installing its serializer package. A configured bridge fails container compilation when its service ID does not exist, preventing a persistence mapping from silently using the wrong serializer.

Serializer output becomes part of the database format. Changes to property names, exclusion rules, groups, custom normalizers, handlers, or serializer metadata may therefore require a data migration. Keep serializer configuration used for persistence stable and ensure that it can reconstruct readonly constructors and nested value objects.

Ramsey UUID bridge

Install Ramsey UUID:

Extend the Ramsey UuidValue base and map its hierarchy to the GUID-backed UuidValueType:

Symfony UID bridge

The optional Symfony UID bridge provides UUID and ULID value bases with two storage strategies each:

• UuidValueType delegates to Symfony's Doctrine UUID type. It uses a native GUID where supported and a fixed 16-byte binary column otherwise.
• UuidValueChar36Type stores the canonical RFC 4122 UUID with hyphens in a fixed CHAR(36) column.
• UlidValueType delegates to Symfony's Doctrine ULID type and uses a native GUID or fixed 16-byte binary column.
• UlidValueChar26Type stores the canonical Base32 ULID in a fixed CHAR(26) column.

Choose one type for your Symfony UUID value hierarchy in the bundle configuration:

Custom generic types

For values backed by a native DBAL type, extend BaseGenericType. It supplies the common validation and conversion flow; the custom type only selects its value hierarchy and underlying DBAL type:

Map EmailAddress::class to EmailAddressType::class under generic_types and include the directory containing its concrete subclasses. Implement StaticGenericType directly only when BaseGenericType cannot model the required conversion.

Custom GenericTypeFactory

Types implementing StaticGenericType are instantiated by the built-in StaticGenericTypeFactory through their createForValue() method. If a Doctrine type needs services from the dependency injection container, implement only the GenericType marker and create it with a custom GenericTypeFactory instead.

For example, given a Doctrine type whose constructor requires an application serializer:

Create a factory that supports that Doctrine type and passes its dependencies to each created instance:

Register the factory as a service tagged with GenericTypeFactoryProvider::TAG:

The value hierarchy is mapped to the custom type in the same way as any built-in generic type:

Symfony orders the tagged factories by their priority from highest to lowest. The built-in factories use GenericTypeFactoryProvider::DEFAULT_PRIORITY (0), so a positive priority allows a custom factory to take precedence. Factories with the same priority retain their container registration order.

GenericTypeFactoryProvider uses the first ordered factory whose supports() method returns true. A factory should therefore support only the Doctrine types it can construct and should validate the supplied value class in create() when the type is restricted to a particular value hierarchy.