README

A Symfony bundle that brings polymorphic relations to Doctrine ORM. It allows a single entity property to reference different entity types — with type safety, IDE support, and optional foreign key constraints.

The Problem

Doctrine ORM doesn't natively support a property that needs to reference multiple unrelated entity types. Imagine a Payment entity with a subject property that can point to either an EshopItem or a Subscription. Standard Doctrine associations require a fixed target type.

This bundle solves it with two approaches:

Mode	DB Columns	Foreign Keys	Best For
Dynamic	`{property}_type` + `{property}_id`	No	Flexible scenarios where FK constraints aren't needed
Explicit	`{property}_type` + one ID column per mapped type	Yes	Scenarios requiring referential integrity

Installation

composer require pechynho/polymorphic-doctrine

Without Symfony Flex, add the bundle to config/bundles.php:

return [
    // ...
    Pechynho\PolymorphicDoctrine\PechynhoPolymorphicDoctrineBundle::class => ['all' => true],
];

Quick Start

1. Mark the entity and define polymorphic properties

use Doctrine\ORM\Mapping as ORM;
use Pechynho\PolymorphicDoctrine\Attributes\DynamicPolymorphicProperty;
use Pechynho\PolymorphicDoctrine\Attributes\EntityWithPolymorphicRelations;
use Pechynho\PolymorphicDoctrine\Attributes\ExplicitPolymorphicProperty;
use Pechynho\PolymorphicDoctrine\Contract\PolymorphicValueInterface;

#[ORM\Entity]
#[EntityWithPolymorphicRelations]
class Payment
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[DynamicPolymorphicProperty([
        'eshop_item' => EshopItem::class,
        'subscription' => Subscription::class,
    ])]
    public PolymorphicValueInterface $dynamicSubject;

    #[ExplicitPolymorphicProperty([
        'eshop_item' => EshopItem::class,
        'subscription' => Subscription::class,
    ])]
    public PolymorphicValueInterface $explicitSubject;
}

2. Generate reference classes (explicit mode only)

php bin/console pechynho:polymorphic-doctrine:generate-reference-classes

3. Work with polymorphic values

class PaymentService
{
    public function __construct(
        private readonly EntityManagerInterface $em,
        private readonly PolymorphicValueFactoryInterface $polymorphicValueFactory,
    ) {}

    public function createPayment(EshopItem $item): void
    {
        $payment = new Payment();

        // Initialize with a value
        $payment->dynamicSubject = $this->polymorphicValueFactory->create(
            Payment::class, 'dynamicSubject', $item
        );

        // Initialize as null
        $payment->explicitSubject = $this->polymorphicValueFactory->create(
            Payment::class, 'explicitSubject'
        );

        $this->em->persist($payment);
        $this->em->flush();
    }
}

Polymorphic Modes

Dynamic Mode

Creates two columns per polymorphic property:

id	dynamic_subject_type	dynamic_subject_id
1	eshop_item	123
2	subscription	456
3	NULL	NULL

Pros: Simple setup, no class generation needed. Cons: No foreign keys — the database cannot enforce referential integrity.

Explicit Mode

Creates a type column plus a dedicated ID column for each mapped entity type:

id	explicit_subject_type	explicit_subject_eshop_item_id	explicit_subject_subscription_id
1	eshop_item	123	NULL
2	subscription	NULL	456
3	NULL	NULL	NULL

Pros: Foreign key on each ID column, referential integrity enforced by the database. Cons: Requires reference class generation, more columns per table.

Working with Polymorphic Values

Creating and Initializing

// With a value
$payment->subject = $this->polymorphicValueFactory->create(Payment::class, 'subject', $entity);

// As null
$payment->subject = $this->polymorphicValueFactory->create(Payment::class, 'subject');

Updating

// Set a new value
$payment->subject->update($newEntity);

// Set to null
$payment->subject->setNull();
// or: $payment->subject->update(null);

Reading

// Check status
$payment->subject->isNull();       // Is the value null?
$payment->subject->isResolvable(); // Does it have a valid type and ID?
$payment->subject->isLoaded();     // Is the entity already loaded in memory?

// Get the entity (lazy-loaded from DB on first access)
$entity = $payment->subject->getValue();

if ($entity instanceof EshopItem) {
    // ...
} elseif ($entity instanceof Subscription) {
    // ...
}

Tip: Always check isNull() before calling getValue().

Type-Narrowing with `getValueAs()`

The getValueAs() method provides a convenient way to retrieve the referenced entity with a narrowed return type. It accepts a class-string<T> and returns T, giving you full IDE autocompletion and static analysis support (PHPStan / Psalm).

// Instead of manual instanceof checks:
$item = $payment->subject->getValueAs(EshopItem::class);
// $item is now typed as EshopItem — full IDE support, no manual narrowing needed

The method throws a ReferenceResolutionException if:

The value is null — always check isNull() first, or handle the exception.
The resolved entity is not an instance of the requested class.

Searching Polymorphic Values

The bundle provides two approaches for querying polymorphic properties via QueryBuilder.

Applier — Simple Approach

Directly modifies the QueryBuilder. Best for straightforward queries.

class PaymentService
{
    public function __construct(
        private readonly EntityManagerInterface $em,
        private readonly PolymorphicSearchExprApplierFactoryInterface $applierFactory,
    ) {}

    public function findByEntity(object $entity): array
    {
        $qb = $this->em->createQueryBuilder()
            ->select('p')->from(Payment::class, 'p');

        $applier = $this->applierFactory->create(Payment::class, 'dynamicSubject', 'p');
        $applier->eq($qb, $entity);

        return $qb->getQuery()->getResult();
    }

    public function findByType(string $entityClass): array
    {
        $qb = $this->em->createQueryBuilder()
            ->select('p')->from(Payment::class, 'p');

        $applier = $this->applierFactory->create(Payment::class, 'explicitSubject', 'p');
        $applier->isInstanceOf($qb, $entityClass);

        return $qb->getQuery()->getResult();
    }
}

Builder — Advanced Approach

Returns expression objects with parameters that can be composed into complex queries.

$builder = $this->builderFactory->create(Payment::class, 'dynamicSubject', 'p');

$eqResult = $builder->eq($item);
$instanceOfResult = $builder->isInstanceOf(EshopItem::class);

$qb->where($qb->expr()->orX($eqResult->expr, $instanceOfResult->expr));

foreach ([$eqResult, $instanceOfResult] as $result) {
    foreach ($result->params as $key => $value) {
        $qb->setParameter($key, $value);
    }
}

Available Operations

Method	Description
`eq($entity)`	Matches the given entity
`neq($entity)`	Does not match the given entity
`in(...$entities)`	Matches any of the given entities
`notIn(...$entities)`	Does not match any of the given entities
`isNull()`	Value is null
`isNotNull()`	Value is not null
`isInstanceOf(...$classes)`	Is an instance of the given type(s)
`isNotInstanceOf(...$classes)`	Is not an instance of the given type(s)

Configuration

# config/packages/pechynho_polymorphic_doctrine.yaml
pechynho_polymorphic_doctrine:
    # Directory for generated reference classes (explicit mode)
    references_directory: '%kernel.cache_dir%/pechynho/polymorphic-doctrine/references'

    # Namespace for generated classes
    references_namespace: 'Pechynho\PolymorphicDoctrine\AutogeneratedReference'

    # Entity discovery settings
    discover:
        cache_directory: '%kernel.cache_dir%/pechynho/polymorphic-doctrine/discover'
        directories:
            - '%kernel.project_dir%/src'

API Reference

Attributes

`#[EntityWithPolymorphicRelations]`

Marks an entity as containing polymorphic relations. Required for entity discovery.

`#[DynamicPolymorphicProperty(array $mapping)]`

Defines a dynamic polymorphic property (two columns: type + ID).

Parameter	Type	Description
`$mapping`	`array`	Map of type keys to entity class names
`$idProperty`	`?string`	Custom ID property name
`$enableDiscriminatorIndex`	`?bool`	Add index on discriminator column
`$enablePairIndex`	`?bool`	Add index on type + ID pair

`#[ExplicitPolymorphicProperty(array $mapping)]`

Defines an explicit polymorphic property (type column + dedicated ID column per mapped type).

Parameter	Type	Description
`$mapping`	`array`	Map of type keys to entity class names or detailed config
`$idProperty`	`?string`	Default ID property name
`$idPropertyType`	`?string`	Default ID property type
`$onDelete`	`?string`	Foreign key ON DELETE action
`$onUpdate`	`?string`	Foreign key ON UPDATE action
`$enableDiscriminatorIndex`	`?bool`	Add index on discriminator column
`$enablePairIndex`	`?bool`	Add index on type + ID pair

Per-type detailed configuration in the mapping:

#[ExplicitPolymorphicProperty([
    'product' => Product::class,
    'service' => [
        'fqcn' => Service::class,
        'idProperty' => 'serviceId',
        'onDelete' => 'CASCADE',
    ],
])]
public PolymorphicValueInterface $subject;

PolymorphicValueInterface

Method	Return Type	Description
`isNull()`	`bool`	Is the value null?
`isResolvable()`	`bool`	Can the value be resolved to an entity?
`isLoaded()`	`bool`	Is the entity already loaded in memory?
`getValue()`	`?object`	Returns the referenced entity (lazy-loaded)
`getValueAs(string $fqcn)`	`T`	Returns the entity narrowed to the given type, or throws
`update(?object $value)`	`void`	Updates the reference to another entity or null
`setNull()`	`void`	Sets the reference to null

Services

Service	Description
`PolymorphicValueFactoryInterface`	Creates polymorphic value instances
`PolymorphicSearchExprBuilderFactoryInterface`	Creates search expression builders
`PolymorphicSearchExprApplierFactoryInterface`	Creates appliers that directly modify QueryBuilder

Console Commands

# Generate reference classes for explicit polymorphic properties
php bin/console pechynho:polymorphic-doctrine:generate-reference-classes

# Clear cache (discovery + reference classes)
php bin/console pechynho:polymorphic-doctrine:cache-clear

Important: After any change to explicit polymorphic property definitions, you must re-run the reference class generation command.

Troubleshooting

Problem	Solution
Reference classes not found (explicit mode)	Run `php bin/console pechynho:polymorphic-doctrine:generate-reference-classes` then `php bin/console cache:clear`
Polymorphic properties not working	Verify the `#[EntityWithPolymorphicRelations]` attribute is on the entity, the bundle is registered, and discovery directories are configured
Slow queries	Enable indexes via `enableDiscriminatorIndex` and `enablePairIndex` on your attributes

Requirements

PHP >= 8.4
Symfony 6.4 / 7.x / 8.x
Doctrine ORM 2.19+ or 3.3+

License

MIT — see LICENSE.

Author

Jan Pech — pechynho@gmail.com

pechynho / polymorphic-doctrine

Maintainers

Package info

Statistics

Security

README

The Problem

Installation

Quick Start

1. Mark the entity and define polymorphic properties

2. Generate reference classes (explicit mode only)

3. Work with polymorphic values

Polymorphic Modes

Dynamic Mode

Explicit Mode

Working with Polymorphic Values

Creating and Initializing

Updating

Reading

Type-Narrowing with `getValueAs()`

Searching Polymorphic Values

Applier — Simple Approach

Builder — Advanced Approach

Available Operations

Configuration

API Reference

Attributes

`#[EntityWithPolymorphicRelations]`

`#[DynamicPolymorphicProperty(array $mapping)]`

`#[ExplicitPolymorphicProperty(array $mapping)]`

PolymorphicValueInterface

Services

Console Commands

Troubleshooting

Requirements

License

Author

pechynho / polymorphic-doctrine

Maintainers

Package info

Statistics

Security

README

The Problem

Installation

Quick Start

1. Mark the entity and define polymorphic properties

2. Generate reference classes (explicit mode only)

3. Work with polymorphic values

Polymorphic Modes

Dynamic Mode

Explicit Mode

Working with Polymorphic Values

Creating and Initializing

Updating

Reading

Type-Narrowing with getValueAs()

Searching Polymorphic Values

Applier — Simple Approach

Builder — Advanced Approach

Available Operations

Configuration

API Reference

Attributes

#[EntityWithPolymorphicRelations]

#[DynamicPolymorphicProperty(array $mapping)]

#[ExplicitPolymorphicProperty(array $mapping)]

PolymorphicValueInterface

Services

Console Commands

Troubleshooting

Requirements

License

Author

Type-Narrowing with `getValueAs()`

`#[EntityWithPolymorphicRelations]`

`#[DynamicPolymorphicProperty(array $mapping)]`

`#[ExplicitPolymorphicProperty(array $mapping)]`