phpgears / cqrs
CQRS base
Installs: 4 191
Dependents: 3
Suggesters: 1
Security: 0
Stars: 4
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: ^7.1
- phpgears/dto: ~0.3.1
Requires (Dev)
- brainmaestro/composer-git-hooks: ^2.8
- friendsofphp/php-cs-fixer: ^2.16
- infection/infection: ^0.13|^0.15
- overtrue/phplint: ^1.2
- phpmd/phpmd: ^2.8
- phpstan/extension-installer: ^1.0.3
- phpstan/phpstan: ^0.12
- phpstan/phpstan-deprecation-rules: ^0.12
- phpstan/phpstan-strict-rules: ^0.12
- phpunit/phpunit: ^7.5|^8.0
- povils/phpmnd: ^2.1
- roave/security-advisories: dev-master
- sebastian/phpcpd: ^4.0
- squizlabs/php_codesniffer: ^3.5
- thecodingmachine/phpstan-strict-rules: ^0.12
This package is auto-updated.
Last update: 2024-10-25 07:36:40 UTC
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.