II. Getting Started

Key Concepts

1. Async Events: are events that are dispatched from Magento when they are triggered
2. Subscribers: is something that listens to one or several async events.

Defining an Async Event

Async events are defined in etc/async_events.xml. The definition only provides an acknowledgement to Magento that such an async event exists. It has to be dispatched by you at a place you find suitable.

    <async_event name="sales.order.created">
        <service class="Magento\Sales\Api\OrderRepositoryInterface" method="get"/>
    </async_event>

1. async_event
   • name - A unique name given to the asynchronous event
2. service
   • class - The class or interface that defines the handler.
   • method - The method which is executed and the return value is published to subscribers.

Dispatching Async Events

Events are dispatched by simply publishing to the EVENT_QUEUE using the Magento\Framework\MessageQueue\PublisherInterface, however it needs to follow a certain structure.

The Magento\Framework\MessageQueue\PublisherInterface::publish takes in two arguments

public function publish($topicName, $data);

The first argument $topicName SHOULD be a string that's defined by the constant \Aligent\AsyncEvents\Helper\QueueMetadataInterface::EVENT_QUEUE

The second argument $data follows a specific structure. It should contain an array of two strings.

1. The first string specifies what async_event to dispatch. (anything that's defined in async_events.xml)
2. The second string SHOUD be a JSON serialised string. The serialised string should contain the named arguments of the service method that resolves the async event.

For example, if your service method was Magento\Sales\Api\OrderRepositoryInterface::get which takes in the following inputs

/**
 * @param int $id The order ID.
 * @return \Magento\Sales\Api\Data\OrderInterface Order interface.
 */
public function get($id);

your $data array should look like

$arguments = ['id' => $orderId];
$data = ['sales.order.created', $this->json->serialize($arguments)]

This is likely to change in a future major version where a AsyncEventMessageInterface would be passed instead of an array of two strings.

Example:

    public function execute(Observer $observer): void
    {
        /** @var Order $object */
        $object = $observer->getEvent()->getData('order');

        $arguments = ['id' => $object->getId()];
        $data = ['sales.order.created', $this->json->serialize($arguments)];

        $this->publisher->publish(QueueMetadataInterface::EVENT_QUEUE, $data);
    }

Notifiers

Each subscription might want to be handled a little differently. This is useful when each subscriber has their own preferred way of receiving notifications.

Your notifiers must implement the Aligent\AsyncEvents\Service\AsyncEvent\NotifierInterface

Example:

<?php

namespace Aligent\AsyncEvents\Service\AsyncEvent;

use Aligent\AsyncEvents\Api\Data\AsyncEventInterface;
use Aligent\AsyncEvents\Helper\NotifierResult;

class ExampleNotifier implements NotifierInterface
{
    /**
     * {@inheritDoc}
     */
    public function notify(AsyncEventInterface $asyncEvent, array $data): NotifierResult
    {
        // Do something here with any data
        $data = "Example notifier with some data: " . $data["objectId"];

        $result = new NotifierResult();
        $result->setSuccess(true);
        $result->setSubscriptionId($asyncEvent->getSubscriptionId());
        $result->setResponseData($data);

        return $result;
    }
}

Creating Subscriptions

Finally, to receive notifications of async events, you have to create subscribers. The module has a REST API to create and manage subscriptions.

{
    "asyncEvent": {
        "event_name": "sales.order.created",
        "recipient_url": "https://example.com/order_created",
        "verification_token": "fv38u07Wdh$R@mRd",
        "metadata": "http"
    }
}