README.md

(CQRS) Command/Query bus implementation for Spiral Framework

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->ack(
            new FindAllUsers($filters->roles())
        )->toArray();
    }
    
    public function show(string $uuid, \Spiral\Cqrs\QueryBusInterface $bus)
    {
        return $bus->ack(
            new FindUserById(Uuid::fromString($uuid))
        )->toArray();
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• butschster
• All Contributors

License

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