feat: support union type identifiers for aggregates and sagas

[dgafka]

Why is this change proposed?

Aggregates and sagas built around multiple identifier sources — e.g. an internally generated ID alongside one supplied by an external system — need a single identifier property that can hold either, without an artificial wrapper type. Ecotone lets #[Identifier] properties use any PHP type, but native union types (InternalId|ExternalId) had never been verified or documented as supported end-to-end.

Description of Changes

• Confirmed union type identifiers work across every identifier-resolution mechanism: native mapping (in-memory and via async channel), aggregate.id metadata override, and #[TargetIdentifier] mapping.
• Confirmed event sourcing needs one extra step: JMS Serializer (used for event-store JSON) can't tell union members apart without a discriminator, so replay fails with a raw Error on an uninitialized property unless the union member classes carry their own discriminator field and the event property declares #[UnionDiscriminator].
• Added end-to-end tests (including a real event-store round trip) proving this pattern works today, with no framework changes needed.

Example

final class InternalId
{
    public function __construct(private string $id) {}
    public function __toString(): string { return $this->id; }
}

final class ExternalId
{
    public function __construct(private string $id) {}
    public function __toString(): string { return $this->id; }
}

#[Aggregate]
final class Ticket
{
    #[Identifier]
    private InternalId|ExternalId $ticketId;

    #[CommandHandler]
    public static function create(CreateTicket $command): self
    {
        $ticket = new self();
        $ticket->ticketId = $command->ticketId;

        return $ticket;
    }
}

For event-sourced aggregates, add a discriminator field on each union member and point #[UnionDiscriminator] at it, so JMS can rebuild the right class on replay:

final class InternalId
{
    public string $type = 'internal';

    public function __construct(private string $id) {}
    public function __toString(): string { return $this->id; }
}

final class TicketWasCreated
{
    public function __construct(
        #[UnionDiscriminator(field: 'type', map: ['internal' => InternalId::class, 'external' => ExternalId::class])]
        public readonly InternalId|ExternalId $ticketId
    ) {}
}

Pull Request Contribution Terms

• I have read and agree to the contribution terms outlined in CONTRIBUTING.