Interceptors
PHP Interceptors Middlewares
Ecotone provide possibility to handle cross cutting concerns via Interceptors.
Interceptor as name the suggest, intercepts the process of handling the message.
You may enrich the message, stop or modify usual processing cycle, call some shared functionality, add additional behavior to existing code without modifying the code itself. If you are familiar with Aspect Oriented Programming or Middleware pattern (used in most of PHP CQRS frameworks) you may find some similarities.
class AdminVerificator
{
#[Before(precedence: 0, pointcut: "Order\Domain\*")]
public function isAdmin(array $payload, array $headers) : void
{
if ($headers["executorId"] != 1) {
throw new \InvalidArgumentException("You need to be administrator in order to register new product");
}
}
}
Precedence defines ordering of called interceptors. The lower the value is, the quicker Interceptor will be called. It's safe to stay with range between -1000 and 1000, as numbers bellow -1000 and higher than 1000 are used by
Ecotone.
The precedence is done within a specific interceptor type. Every interceptor has
Pointcut attribute, which describes for specific interceptor, which endpoints it should intercept.CLASS_NAME- indicates intercepting specific class or interface or class containing attribute on method or class levelexpression||expression- Indicating one expression or another e.g.Product\*||Order\*
There are four types of interceptors. Each interceptor has it role and possibilities.
Interceptors are called in following order:
- Before
- Around
- After
- Presend
Before interceptor is called before endpoint is executed.
Before interceptors can used in order to stop the flow, throw an exception or enrich the Message.
We will intercept Command Handler with verification if executor is an administrator.Let's start by creating
Attribute called IsAdministrator in new namepace.#[\Attribute]
class RequireAdministrator {}
Let's create our first
Before Interceptor. class AdminVerificator
{
#[Before(pointcut: RequireAdministrator::class)]
public function isAdmin(array $payload, array $headers) : void
{
if ($headers["executorId"] != 1) {
throw new \InvalidArgumentException("You need to be administrator in order to register new product");
}
}
}
We are using in here Pointcut here which is looking for
#[RequireAdministrator] annotation in each of registered Endpoints.
The void return type is expected in here. It tells Ecotonethat, this Before Interceptor is not modifying the Message and message will be passed through. The message flow however can be interrupted by throwing exception.Now we need to annotate our Command Handler:
#[CommandHandler]
#[RequireAdministrator]
public function changePrice(ChangePriceCommand $command) : void
{
// do something with $command
}
Whenever we call our command handler, it will be intercepted by AdminVerificator now.
There is one thing worth to mention. Our
Command Handler is using ChangePriceCommandclass and our AdminVerificator interceptor is using array $payload. They are both the same payload of the Message, but converted in the way Endpoint expected. If return type is
not void new modified based on previous Message will be created from the returned type.
We will enrich Message payload with timestamp.#[\Attribute]
class AddTimestamp {}
class TimestampService
{
#[Before(pointcut: AddTimestamp::class)]
public function add(array $payload) : array
{
return array_merge($payload, ["timestamp" => time()]);
}
}
class ChangePriceCommand
{
private int $productId;
private int $timestamp;
}
#[CommandHandler]
#[AddTimestamp]
public function changePrice(ChangePriceCommand $command) : void
{
// do something with $command and timestamp
}
Suppose we want to add executor Id, but as this is not part of our Command, we want add it to our Message Headers.
#[\Attribute]
class AddExecutor {}
class TimestampService
{
#[Before(pointcut: AddExecutor::class, changeHeaders: true)]
public function add() : array
{
return ["executorId" => 1];
}
}
If return type is
not void new modified based on previous Message will be created from the returned type. If we additionally add changeHeaders: trueit will tell Ecotone, that we we want to modify Message headers instead of payload. #[CommandHandler]
#[AddExecutor]
public function changePrice(ChangePriceCommand $command, array $metadata) : void
{
// do something with $command and executor id $metadata["executorId"]
}
Use
Message Filter, to eliminate undesired messages based on a set of criteria.
This can be done by returning null from interceptor, if the flow should proceed, then payload should be returned.#[\Attribute]
class SendNotificationOnlyIfInterested {}
class NotificationFilter
{
#[Before(pointcut: SendNotificationOnlyIfInterested::class, changeHeaders: true)]
public function filter(PriceWasChanged $event) : ?array
{
if ($this->isInterested($event) {
return $event; // flow proceeds
}
return null; // message is eliminated, flow stops.
}
}
If return type is
not void new modified based on previous Message will be created from the returned type. If we additionally add changeHeaders=trueit will tell Ecotone, that we we want to modify Message headers instead of payload. #[EventHandler]
#[SendNotificationOnlyIfInterested]
public function sendNewPriceNotification(ChangePriceCommand $event) : void
{
// do something with $event
}
The
Around Interceptor have access to actual Method Invocation.This does allow for starting some procedure and ending after the invocation is done. At this moment all conversions are done, so we can't convert payload to different type. Around interceptoris a good place for handling transactions or logic shared between different endpoints, that need to access invoked object. class TransactionInterceptor
{
#[Around(pointcut: Ecotone\Modelling\CommandBus::class)]
public function transactional(MethodInvocation $methodInvocation)
{
$this->connection->beginTransaction();
try {
$result = $methodInvocation->proceed();
$this->connection->commit();
}catch (\Throwable $exception) {
$this->connection->rollBack();
throw $exception;
}
return $result;
}
}
As we used
Command Bus interface as pointcut, we told Ecotone that it should intercept Command Bus Gateway. Now whenever we will call any method on Command Bus, it will be intercepted with transaction.
The other powerful use case for Around Interceptor is intercepting Aggregate.
Suppose we want to verify, if executing user has access to the Aggregate.#[Aggregate]
#[IsOwnedByExecutor]
class Person
{
private string $personId;
#[CommandHandler]
public function changeAddress(ChangeAddress $command) : void
{
// change address
}
public function hasPersonId(string $personId) : bool
{
return $this->personId === $personId;
}
}
We have placed
@IsOwnerOfPerson annotation as the top of class. For interceptor pointcut it means, that each endpoint defined in this class should be intercepted. No need to add it on each Command Handler now.#[\Attribute]
class IsOwnedByExecutor {}
class IsOwnerVerificator
{
#[Around(pointcut: IsOwnedByExecutor::class)]
public function isOwner(MethodInvocation $methodInvocation, Person $person, array $metadata)
{
if (!$person->hasPersonId($metadata["executoId"]) {
throw new \InvalidArgumentException("No access to do this action!");
}
$result = $methodInvocation->proceed();
}
}
After interceptor is called after endpoint execution has finished.
It does work exactly the same as Before Interceptor.
After interceptor can used to for example to enrich QueryHandler result.namespace Order\ReadModel;
class OrderService
{
#[QueryHandler]
public function getOrderDetails(GetOrderDetailsQuery $query) : array
{
return ["orderId" => $query->getOrderId()]
}
}
class AddResultSet
{
#[After(pointcut: "Order\ReadModel\*")
public function add(array $payload) : array
{
return ["result" => $payload];
}
}
We will intercept all endpoints within Order\ReadModel namespace, by adding result coming from the endpoint under
result key.You may access attribute from the intercepted endpoint in order to perform specific action
#[\Attribute]
class Cache
{
public string $cacheKey;
public int $timeToLive;
public function __construct(string $cacheKey, int $timeToLive)
{
$this->cacheKey = $cacheKey;
$this->timeToLive = $timeToLive;
}
}
class NotificationFilter
{
#[After]
public function filter($result, Cache $cache) : ?array
{
$this->cachingSystem($cache->cacheKey, $result, $cache->timeToLive);
}
}
If you type hint for specific attribute, you do not need to add pointcut, as it will resolve it automatically.
class ProductsService
{
#[QueryHandler]
#[Cache("hotestProducts", 120)]
public function getHotestProducts(GetOrderDetailsQuery $query) : array
{
return ["orderId" => $query->getOrderId()]
}
}
Presend Interceptor is called before Message is actually send to the channel.
In synchronous channel there is no difference between Before and Presend.
The difference is seen when the channel is asynchronous.
Before Interceptor is called after message is sent to the channel, before execution of Endpoint.
Presend Interceptor is called exactly before message is sent to the channel.
Presend Interceptor can be used for example, when Command Bus is called from HTTP Controller.
Then we may want to verify if data is correct and if not filter out the Message, or we may want to check, if user has enough permissions to do the action or validate payload.
This will keep our asynchronous channel free of incorrect messages.class VerifyIfAuthenticated
{
#[Presend(pointcut: Ecotone\Modelling\Attribute\CommandHandler::class)]
public function verify(#[Header("executorId")] ?string $executorId) : void
{
if (!$executorId) {
throw new \InvalidArgumentException("User must be logged");
}
}
}
class IsEventAlreadyHandled
{
private Storage $storage;
#[Presend(pointcut: Ecotone\Modelling\Attribute\EventHandler::class)]
public function verify($payload, #[Header("messageId")] string $messageId)
{
if ($this->storage->isHandled($messageId)) {
return null;
}
return $payload;
}
}
Last modified 1yr ago