messaging.md

Messaging

Prooph\Common\Messaging provides basic message implementations. These message classes are dispatched by prooph/service-bus, persisted by prooph/event-store and applied to aggregate roots by prooph/event-sourcing.

DomainMessage

Prooph\Common\Messaging\DomainMessage is the basic class for all prooph messages. It is declared abstract and requires implementers to provide a messageType and implementations for public function payload(): array and protected function setPayload(array $payload).

A class constructor is not defined for Prooph\Common\Messaging\DomainMessage. It is up to you how you want to instantiate your messages. Just call DomainMessage::init() within your message constructors to initialize a message object with defaults.

Each Prooph\Common\Messaging\DomainMessage

• has a Ramsey\Uuid uuid to identify the message in logs or in event streams, allows for duplicate checks and so on,
• a string messageName which defaults to the FQCN of the message, used to reconstitute a message
• a int version defaults to 0, mainly required for domain events to track version of corresponding aggregate roots
• array metadata can contain scalar types or sub arrays, it is recommended to only use it as a hash table for scalar values
• DateTimeImmutable createdAt is set when DomainMessage::init is invoked, implementers can override protected $dateTimeFormat = \DateTime::ISO8601 to use another format when message is serialized/deserialized.

Payload

Since prooph/common 3.x payload is no longer part of the message object but instead methods are required to get/set the payload. Payload is the data transported by the message. It should only consist of scalar types and sub arrays so that it can easily be json_encoded and json_decoded. Implementers don't need to manage a payload property but public function payload() should return the message data. The protected function setPayload(array $payload) method instead should reconstitute message data from given payload array.

Here is a simple example of a command:

<?php

final class RegisterUser extends \Prooph\Common\Messaging\Command
{
    /**
     * @var UserId
     */
    private $userId;

    /**
     * @var string
     */
    private $username;

    public function __construct(UserId $userId, $username)
    {
        $this->userId = $userId;
        $this->username = $username;
        //Initialize message properties: uuid, messageName, createdAt
        $this->init();
    }

    public function payload(): array
    {
        return [
            'user_id' => $this->userId->toString(),
            'username' => $this->username
        ];
    }


    protected function setPayload(array $payload): void
    {
        //we skip assertions here for the sake of simplicity
        $this->userId = UserId::fromString((string)$payload['user_id']);
        $this->username = (string)$payload['username'];
    }
}

PayloadConstructable

A very simple way to handle payload data is to provide it as an array at construction time. prooph/common ships with a Prooph\Common\Messaging\PayloadConstructable interface and a Prooph\Common\Messaging\PayloadTrait. Use them if you don't want to worry about payload handling.

Metadata

Message metadata is an array of key => value pairs, where the key is a string and the value has to be a scalar type. Note that you should NOT use metadata keys beginning with an underscore "_", because this is used internally.

Custom Messages

If you prefer to work with your own message implementations and want to use third party serializers everything you need to do is to implement the interface Prooph\Common\Messaging\Message and inject custom implementations of Prooph\Common\Messaging\MessageFactory and Prooph\Common\Messaging\MessageConverter into prooph components which deal with message conversion from/to plain PHP arrays. Please refer the docs of the components for details.

Migration from Prooph\Common v3

The method Prooph\Common\Messaging\Message::version(): int has been removed in v4. If you rely on the version-method you have to implement it yourself and store the version in the metadata, f.e.

    public function version(): int
    {
        return $this->metadata['version'];
    }
    
    public function withVersion(int $version): Message
    {
        $self = clone $this;
        $self->setVersion($version);
        return $self;
    }
    
    protected function setVersion(int $version): void
    {
        $this->metadata['version'] = $version;
    }