Multi-entity aggregates

[brendt]

Axon has what seems like a great concept called "multi-entity aggregates" (https://docs.axoniq.io/reference-guide/axon-framework/axon-framework-commands/modeling/multi-entity-aggregates)

The tl;dr is that while there's still one aggregate root, it can be split into several internal entities. From the Axon docs:

Complex business logic often requires more than what an Aggregate with only an Aggregate Root can provide. In that case, it is important that the complexity is spread over a number of 'Entities' within the aggregate.

Maybe it's worth discussing this paradigm and consider adding it in v5?

[brendt]

Let's discuss an example in PHP from an existing project. We're building an e-shop that has the concept of "a cart". There's a use case describing how a cart can be "locked". This is a kind of special state, since a cart can be locked both before and after checkout. If the cart is locked after checkout and the payment were to fail, the cart should go back to its pending state, but still be locked.

Currently all of this is modeled in one aggregate root: the CartAggregateRoot. It has a $locked boolean that's used in several methods to determine the flow.

If we could use multi-entity aggregates, we could model the "locked state" as a separate entity. It would look something like this:

class CartLock extends AggregateEntity
{
    private bool $locked = false;

    public function isLocked(): bool
    {
        return $this->locked;
    }
    
    public function lock(): self
    {
        $this->recordThat(…);
        
        return $this;
    }

    protected function applyLocked(CartLocked $event): void
    {
        $this->locked = true;
    }
    
    public function unlock(): self
    {
        $this->recordThat(…);
        
        return $this;
    }

    protected function applyUnlocked(CartUnlocked $event): void
    {
        $this->locked = false;
    }
}

The cart aggregate root in turn would be able to use this entity like so:

class CartAggregateRoot extends AggregateRoot
{
    private CartLock $cartLock;

    public function __construct()
    {
        $this->cartLock = new CartLock();
    }

    public function fail(?string $message): void
    {
        // …
        
        $this->recordThat(new CartFailed(
            $this->cartUuid(),
            $message
        ));
    }

    public function applyFailed(CartFailed $event): void
    {
        if ($this->cartLock->isLocked()) {
            // … 
        } else {
            // …   
        }
    }
}

Right now, all of this logic happens in the CartAggregateRoot, and it's growing rather large. Mind you that I've simplified the example quite a bit compared to the real application, in practice entities would be even more useful.

[freekmurze]

This seems like a nice / straightforward way to move logic outside of an AR. How would recordThat on the AggregateEntity know on which aggregate root events should be persisted?

[brendt]

Each entity should keep track of its parent aggregate root UUID. I'll make a proof of concept later today.

[morrislaptop]

Will the entity be able to access parent state to make decisions? Perhaps in a read only fashion? It's starting to feel a lot like Vue components 🥼

[brendt]

@morrislaptop yes, entities and aggregate roots are allowed to read each other's state within the same aggregate. Exposing state to the outside is still not done.

[brendt]

There's one piece missing to make all of this work. Axon models its AR methods as command handlers. Instead of directly calling $cart->fail(), it would look something like this:

$commandBus->dispatch(new FailCartCommand($cartUuid, …));

The command bus will map the command to an AR method. This is a major paradigm shift from how our package current works. The advantage of it though is that commands can also be dispatched automatically to aggregate entities without the user needing to know the mapping.

Without commands, we'd have to add an extra method on the cart AR to be able to lock and unlock the internal entity:

class CartAggregateRoot extends AggregateRoot
{
    // …

    public function lock(): self
    {
        $this->cartLock->lock();

        return $this;
    }

    public function unlock(): self
    {
        $this->cartLock->unlock();

        return $this;
    }
}

While this is not the biggest issue, it's a little more cumbersome. I'm not suggesting we should add a command bus right now, but I felt it necessary to mention nevertheless.

[freekmurze]

It feels a bit more heavy weight indeed. Let's not add it until it's actually useful for our own stuff.

[brendt]

Here's an implementation that doesn't require a command bus: #196