README

👁 PHP
👁 Latest Version on Packagist
👁 Total Downloads
👁 run-tests

It's a lightweight messaging facade. It allows you to define the API of your model with the help of messages.

• Command messages describe actions your model can handle.
• Query messages describe available information that can be fetched from your (read) model.

Requirements

Make sure that your server is configured with following PHP version and extensions:

• PHP 8.1+
• Spiral framework 3.0+

Installation

You can install the package via composer:

composer require spiral-packages/cqrs

After package install you need to register bootloader from the package.

protected const LOAD = [
 // ...
 \Spiral\Cqrs\Bootloader\CqrsBootloader::class,
];

Note: if you are using spiral-packages/discoverer, you don't need to register bootloader by yourself.

Usage

You can also register command and query handlers via attributes

Commands

Command definition

class StoreUser implements \Spiral\Cqrs\CommandInterface
{
 public function __construct(
 public Uuid $uuid,
 public string $username,
 public string $password,
 public \DateTimeImmutable $registeredAt,
 ) {
 }
}

Command handler definition

To register command handler you just need to add attribute on method that should be invoked.

class StoreUserHandler
{
 public function __construct(
 private EntityManagerInterface $entityManager
 ) {

 }

 #[\Spiral\Cqrs\Attribute\CommandHandler]
 public function __invoke(StoreUser $command)
 {
 $this->entityManager->persist(
 new User(
 $command->uuid,
 $command->username,
 $command->password,
 $command->registeredAt
 )
 );

 $this->entityManager->run();
 }
}

Dispatch command

use Ramsey\Uuid\Uuid;

class UserController
{
 public function store(UserStoreRequest $request, \Spiral\Cqrs\CommandBusInterface $bus)
 {
 $bus->dispatch(new StoreUser(
 $uuid = Uuid::uuid4(),
 $request->getUsername(),
 $request->getPassword(),
 new \DateTimeImmutable()
 ));

 return $uuid;
 }
}

Queries

Query definition

class FindAllUsers implements \Spiral\Cqrs\QueryInterface
{
 public function __construct(
 public array $roles = []
 ) {
 }
}

class FindUserById implements \Spiral\Cqrs\QueryInterface
{
 public function __construct(
 public Uuid $uuid
 ) {
 }
}

Query handler definition

class UsersQueries
{
 public function __construct(
 private UserRepository $users
 ) {
 }

 #[\Spiral\Cqrs\Attribute\QueryHandler]
 public function findAll(FindAllUsers $query): UserCollection
 {
 $scope = [];
 if ($query->roles !== []) {
 $scope['roles'] = $query->roles
 }

 return new UserCollection(
 $this->users->findAll($scope)
 );
 }

 #[\Spiral\Cqrs\Attribute\QueryHandler]
 public function findById(FindUserById $query): UserResource
 {
 return new UserResource(
 $this->users->findByPK($query->uuid)
 );
 }
}

Dispatch queries

use Ramsey\Uuid\Uuid;

class UserController
{
 public function index(UserFilters $filters, \Spiral\Cqrs\QueryBusInterface $bus)
 {
 return $bus->ask(
 new FindAllUsers($filters->roles())
 )->toArray();
 }

 public function show(string $uuid, \Spiral\Cqrs\QueryBusInterface $bus)
 {
 return $bus->ask(
 new FindUserById(Uuid::fromString($uuid))
 )->toArray();
 }
}

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.