prooph/common

Common classes shared between prooph components

Shared Kernel

Prooph components work with php-fig standards and other de facto standards like Container-Interop whenever possible. But they also share some prooph software specific classes. These common classes are included in this repository.

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()
    {
        return [
            'user_id' => $this->userId->toString(),
            'username' => $this->username
        ];
    }


    protected function setPayload(array $payload)
    {
        //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.

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.

ActionEventEmitter

To add event-driven capabilities to prooph components prooph/common provides a basic implementation of an event emitter and an default action event object. We call these events action events because we want to differentiate them from domain events.

A domain event describes something happened in the past.

An action event on the other side is an communication object used to pass parameters from one listener to the next listener during an event-driven process. Furthermore an action event can be stopped which in turn stops the running process. All prooph components type hint the interfaces Prooph\Common\Event\ActionEventEmitter, Prooph\Common\Event\ActionEventListener/ListenerAggregate, Prooph\Common\Event\ActionEvent and therefor allow the usage of custom implementations. If you don't inject your own implementations all components fall back to the default implementations provided by prooph/common.

Support

• Ask questions on prooph-users google group.
• File issues at https://github.com/prooph/common/issues.

Contribute

Please feel free to fork and extend existing or add new features and send a pull request with your changes! To establish a consistent code quality, please provide unit tests for all your changes and may adapt the documentation.