README

CQRS

CQRS base classes and handling interfaces

This package only provides the building blocks to CQRS

Installation

Composer

composer require phpgears/cqrs

Usage

Require composer autoload file

require './vendor/autoload.php';

Commands

Commands are DTOs that carry all the information for an action to happen

You can create your own by implementing Gears\CQRS\Command or extend from Gears\CQRS\AbstractCommand which ensures command immutability and payload is composed only of scalar values which is a very interesting capability. AbstractCommand has a protected constructor forcing you to create custom static named constructors

use Gears\CQRS\AbstractCommand;

class CreateUserCommand extends AbstractCommand
{
    public static function fromPersonalData(
        string $name,
        string lastname,
        \DateTimeImmutable $birthDate
    ): self {
        return new self([
            'name' => $name,
            'lastname' => $lastname,
            'birthDate' => $birthDate->format('U'),
        ]);
    }
}

In case of a command without any payload you could extend Gears\CQRS\AbstractEmptyCommand

use Gears\CQRS\AbstractEmptyCommand;

class CreateUserCommand extends AbstractEmptyCommand
{
    public static function instance(): self {
        return new self();
    }
}

Async commands

Having command assuring all of its payload is composed only of scalar values proves handy when you want to delegate command handling to a message queue system such as RabbitMQ, Gearman or Apache Kafka, serializing/deserializing scalar values is trivial in any format and language

Asynchronous behaviour must be implemented at CommandBus level, command bus must be able to identify async commands (a map of commands, implementing an interface, by a payload parameter, ...) and enqueue them

If you want to have asynchronous behaviour on your CommandBus have a look phpgears/cqrs-async, there you'll find all the necessary pieces to start your async command bus, for example using queue-interop with phpgears/cqrs-async-queue-interop

Queries

Queries are DTOs that carry all the information for a request to be made to the data source

You can create your own by implementing Gears\CQRS\Query or extend from Gears\CQRS\AbstractQuery which ensures query immutability and payload is composed only of scalar values. AbstractQuery has a protected constructor forcing you to create a custom static named constructors

use Gears\CQRS\AbstractQuery;

class FindUserQuery extends AbstractQuery
{
    public static function fromName(string $name): self 
    {
        return new self(['name' => $name]);
    }
}

In case of a query without any payload you could extend Gears\CQRS\AbstractEmptyQuery

use Gears\CQRS\AbstractEmptyQuery;

class FindAllUsersQuery extends AbstractEmptyQuery
{
    public static function instance(): self {
        return new self();
    }
}

Handlers

Commands and Queries are handed over to Gears\CQRS\CommandHandler and Gears\CQRS\QueryHandler respectively on their corresponding buses

AbstractCommandHandler and AbstractQueryHandler are provided in this package, this abstract classes verifies the type of the command/query so you can focus only on implementing the handling logic

class CreateUserCommandHandler extends AbstractCommandHandler
{
    protected function getSupportedCommandType(): string
    {
        return CreateUserCommand::class;
    }

    protected function handleCommand(Command $command): void
    {
        /* @var CreateUserCommand $command */

        $user = new User(
            $command->getName(),
            $command->getLastname(),
            $command->getBirthDate()
        );

        // ...
    }
}

class FindUserQueryHandler extends AbstractQueryHandler
{
    protected function getSupportedQueryType(): string
    {
        return FindUserQuery::class;
    }

    protected function handleCommand(Query $query): DTO
    {
        /* @var FindUserQuery $query */

        // Retrieve user from persistence by it's name $query->getName()

        return new UserDTO(/* parameters */);
    }
}

Have a look at phpgears/dto fo a better understanding of how commands and queries are built out of DTOs and how they hold their payload

Buses

Only Gears\CQRS\CommandBus and Gears\CQRS\QueryBus interfaces are provided, you can easily use any of the good bus libraries available out there by simply adding an adapter layer

Implementations

CQRS buses implementations currently available

phpgears/cqrs-symfony-messenger uses Symfony's Messenger
phpgears/cqrs-tactician uses League's Tactician

Contributing

Found a bug or have a feature request? Please open a new issue. Have a look at existing issues before.

See file CONTRIBUTING.md

License

See file LICENSE included with the source code for a copy of the license terms.

phpgears / cqrs

Maintainers

Details