hyphaeworks / nullable-embeddable-bundle
Symfony bundle for handling nullable Doctrine embeddables
Package info
github.com/hyphaeworks/nullable-embeddable-bundle
Type:symfony-bundle
pkg:composer/hyphaeworks/nullable-embeddable-bundle
Requires
- php: ^8.2
- doctrine/doctrine-bundle: ^2.12 || ^3.0
- doctrine/orm: ^2.17 || ^3.0
- symfony/framework-bundle: ^6.4 || ^7.4 || ^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.65
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.1
- phpstan/phpstan-doctrine: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpstan/phpstan-strict-rules: ^2.0
- phpunit/phpunit: ^11.5 || ^12.0
- symfony/error-handler: ^6.4.44 || ^7.4.17 || ^8.1.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is not auto-updated.
Last update: 2026-11-17 19:44:19 UTC
README
A nullable embeddable bundle that just works.
Doctrine always creates an embeddable
object on load, even when all its columns are NULL. This Symfony bundle
sets such an empty embeddable to null instead: install it, type the property as nullable, done.
Installation
composer require hyphaeworks/nullable-embeddable-bundle
Register the bundle in config/bundles.php if Symfony Flex did not do it for you. No configuration is needed.
Hyphaeworks\NullableEmbeddableBundle\NullableEmbeddableBundle::class => ['all' => true],
| Package | Versions |
|---|---|
| PHP | 8.2 to 8.5 |
| Symfony | 6.4, 7.4, 8.x |
| doctrine/orm | 2.17+, 3.x |
| doctrine/doctrine-bundle | 2.12+, 3.x |
Usage
Give the embedded property a nullable type. That's all:
use Doctrine\ORM\Mapping as ORM; #[ORM\Embeddable] final class EmailAddress { public function __construct( #[ORM\Column(nullable: true)] public ?string $address = null, ) { } } #[ORM\Entity] class User { #[ORM\Embedded(class: EmailAddress::class)] private ?EmailAddress $emailAddress = null; }
An untyped property needs the #[NullableEmbedded] attribute instead:
#[ORM\Embedded(class: EmailAddress::class)] #[NullableEmbedded] private $emailAddress;
This works with attribute and XML mapping, nested embeddables, inherited properties and mapped superclasses.
How it works
Rules
- An embeddable is empty when every mapped column in it is
nullor uninitialized. Unmapped and static properties are ignored;0,''andfalseare values. - Nested embeddables are checked innermost first: an outer embeddable that only holds an empty inner one becomes
nulltoo. - A property is only set to
nullwhen that is possible. These are left exactly as Doctrine loads them, because they may be deliberate:- a non-nullable embedded property (
EmailAddress $emailAddress); - a
readonlyembedded property, which cannot be changed after Doctrine has set it; - an embeddable with a
NOT NULLcolumn: the database never returns all of its columns asNULL, so there is nothing to set tonull. To storenullin such a property, every column needsnullable: true.
- a non-nullable embedded property (
- Avoid
readonlyin embeddables if you userefresh(): Doctrine itself cannot refresh an entity with areadonlyembedded property or an embeddable withreadonlyproperties, with or without this bundle. - Single-column value objects (an email address, a currency code) are often better served by a custom DBAL type.
Metadata cache
The bundle hooks into entities with nullable embedded properties through Doctrine's class metadata, so the hook is stored in the metadata cache. Default Symfony setups rebuild that cache on deploy. If yours lives in a persistent store (Redis, Memcached, a database), clear it after installing or upgrading the bundle and after changing an embedded property's mapping, or empty embeddables are silently kept:
bin/console doctrine:cache:clear-metadata
Performance
Entities without a nullable embedded property are not affected. The others cost about 1µs more per loaded entity.
License
MIT. See LICENSE.
