repository.md

description	Fetching and storing Aggregates with repositories in Ecotone PHP

Fetching/Storing Aggregates

Default flow

In default flow there is no need to fetch or store Aggregates, because this is done for us. We simply need to trigger an Command via CommandBus. However in some cases, you may want to retake orchestration flow and do it directly. For that cases Business Repository Interface or Instant Fetch Aggregate can help you.

Business Repository Interface

Special type of Business Interface is Repository.
This Interface allows us to simply load and store our Aggregates directly. In situations when we call Command directly in our Aggregates we won't be in need to use it. However for some specific cases, where we need to load Aggregate and store it outside of Aggregate's Command Handler, this business interface becomes useful.

{% hint style="info" %} To make use of this Business Interface, we need our Aggregate Repository being registered. {% endhint %}

interface OrderRepository
{
    #[Repository]
    public function getOrder(string $orderId): Order;

    #[Repository]
    public function findOrder(string $orderId): ?Order;

    #[Repository]
    public function save(Order $order): void;
}

Ecotone will read type hint to understand which Aggregate you would like to fetch or save.

{% hint style="success" %} Implementation will be delivered by Ecotone. All you need to do is to define the interface and it will available in your Dependency Container {% endhint %}

Pure Event Sourced Repository

When using Pure Event Sourced Aggregate, instance of Aggregate does not hold recorded Events. Therefore passing aggregate instance would not contain any information about recorded events.
For Pure Event Sourced Aggregates, we can use direct event passing to the repository:

interface OrderRepository
{
    #[Repository]
    public function getOrder(string $orderId): Order;

    #[Repository]
    public function findOrder(string $orderId): ?Order;

    #[Repository]
    #[RelatedAggregate(Order::class)]
    public function save(string $aggregateId, int $currentVersion, array $events): void;
}

Instant Fetch Aggregate

Fetch aggregates directly in your handlers without repository injection boilerplate. Aggregates arrive automatically via the #[Fetch] attribute, keeping handler code focused on business logic.

You'll know you need this when:

• Every aggregate command handler follows the same pattern: inject repository, fetch aggregate, call method, save
• Repository injection boilerplate obscures the actual business logic in your handlers
• You want your domain code to express "what happens" without "how to load it"

{% hint style="success" %} Instant Fetch Aggregate is available as part of Ecotone Enterprise. {% endhint %}

To do instant fetch of Aggregate we will be using Fetch Attribute.
Suppose we want PlaceOrder Command Handler, and we want to fetch User Aggregate:

#[CommandHandler]
public function placeOrder(
    PlaceOrder $command,
    #[Fetch("payload.userId")] User $user
): void {
    // do something    
}

Fetch using expression language to evaluate the expression given inside the Attribute.
For example having above "payload.userId" and following Command:

class readonly PlaceOrder
{
    public function __construct(
        public string $orderId,
        public string $userId,
        public string $productId
    ) {
    }

Ecotone will use userId from the Command to fetch User Aggregate instance.
&#xNAN;"payload" is special variable within expression that points to our Command, therefore whatever is available within the Command is available for us to do the fetching.
This provides quick way of accessing related Aggregates without the need to inject Repositories.

Allowing non existing Aggregates

By default Ecotone will throw Exception if Aggregate is not found, we can change the behaviour simply by allowing nulls in our method declaration:

#[CommandHandler]
public function placeOrder(
    PlaceOrder $command,
    #[Fetch("payload.userId")] ?User $user // we marked it as possible null
): void {
    // do something    
}

Fetching with Closures

On PHP 8.5+ the identifier can be resolved with a Closure instead of Expression Language string, keeping full type safety and IDE support:

#[CommandHandler]
public function placeOrder(
    PlaceOrder $command,
    #[Fetch(static function (#[Payload] PlaceOrder $command): string {
        return $command->userId;
    })] User $user
): void {
    // do something    
}

The Closure parameters resolve like in regular Message Handler (#[Payload], #[Header], #[Reference] and more). Read more in Closures as Expressions.

Accessing Message Headers

We can also use Message Headers to fetch our related Aggregate instance:

#[CommandHandler]
public function placeOrder(
    PlaceOrder $command,
    #[Fetch("headers['userId']")] User $user
): void {
    // do something    
}

Using External Services

In some cases we may not have enough information to provide correct Identifier, for example that may require some mapping in order to get the Identifier. For this cases we can use "reference" function to access any Service from Depedency Container in order to do the mapping.

#[CommandHandler]
public function placeOrder(
    PlaceOrder $command,
    #[Fetch("reference('emailToIdMapper').map(payload.email)")] User $user
): void {
    // do something    
}