Download the PHP package nepada/message-bus without Composer
On this page you can find all versions of the php package nepada/message-bus. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download nepada/message-bus
More information about nepada/message-bus
Files in nepada/message-bus
Package message-bus
Short Description Opinionated message bus built on top of symfony/messenger.
License BSD-3-Clause
Informations about the package message-bus
Message Bus
Opinionated message bus built on top of symfony/messenger largely based on the ideas and code base of damejidlo/message-bus, originally developed by Ondřej Bouda.
Installation
Via Composer:
Conventions
We define two types of messages and corresponding message buses - commands and events.
Commands
Command implementation must adhere to these rules:
- class must implement
Nepada\Commands\Command
interface - class must be named
<command-name>Command
- class must be final
- class must be readonly
- command name should be in imperative form ("do something")
- command must be a simple immutable DTO
- command must not contain entities, only references (i.e.
int $orderId
, notOrder $order
)
Examples of good command class names:
RejectOrderCommand
CreateUserCommand
Command handler implementation must adhere to these rules:
- class must implement
Nepada\Commands\CommandHandler
interface - class must be named
<command-name>Handler
- class must be final
- class must implement method named
__invoke
__invoke
method must have exactly one parameter named$command
__invoke
method parameter must be typehinted with specific command class__invoke
method return type must bevoid
__invoke
method must be annotated with@throws
tags if specific exceptions can be thrown
Example:
Every command must have exactly one handler.
Events
Events must be dispatched during command handling only.
Event implementation must adhere to these rules:
- class must implement
Nepada\Events\Event
interface - class must be named
<event-name>Event
- class must be final
- class must be readonly
- event name should be in past tense ("something happened")
- event must be a simple immutable DTO
- event must not contain entities, only references (i.e.
int $orderId
, notOrder $order
)
Examples of good event class names:
OrderRejectedEvent
UserRegisteredEvent
Event subscriber implementation must adhere to these rules:
- class must implement
Nepada\Events\EventSubscriber
interface - class must be named
<do-something>On<event-name>
- class must be final
- class must implement method named
__invoke
__invoke
method must have exactly one parameter named$event
__invoke
method parameter must be typehinted with specific event class__invoke
method return type must bevoid
__invoke
method must be annotated with@throws
tags if specific exceptions can be thrown
Example:
Every event may have any number of subscribers, or none at all.
Configuration & Usage
Enforcing conventions by static analysis
Most of the conventions described above may be enforced by static analysis. The analysis should be run during the compilation of DI container, triggering it at application runtime is not recommended.
Bleeding edge (new rules)
To maintain backwards compatibility new rules are not enforced by default. They can be enabled by passing $bleedingEdge
flag when creating validator configuration, e.g. MessageHandlerValidationConfiguration::command(true)
.
These rules will be enabled in the next major version: (none at the moment)
Extracting handled message type from handler class
Use MessageTypeExtractor
to retrieve the message type that a given command handler or event subscriber handles:
Logging
LoggingMiddleware
implements logging into standard PSR-3 logger.
Start of message handling and its success or failure are logged separately.
Logging context is filled with the extracted attributes of command or event DTO.
Nested message handling
Generally, it's not a good idea to execute commands from within another command handler.
You can completely forbid this behavior with PreventNestedHandlingMiddleware
.
Configuration
It is completely up to you to use the provided building blocks together with Symfony Messenger and configure one or more instances of command and/or event buses.
A minimal setup in pure PHP might look something like this:
Note the usage of DispatchAfterCurrentBusMiddleware
- this is necessary to ensure that events produced during the handling of a command are handled only after the command handling successfully finishes.
For Nette Framework integration, consider using nepada/message-bus-nette.
Extensions
- nepada/message-bus-doctrine Doctrine ORM integration - transaction handling, collecting and emitting domain events from entities, etc.
- nepada/message-bus-nette Nette Framework DI extension.
- nepada/phpstan-message-bus adding support for propagating checked exceptions thrown out of command handlers up to the command bus caller
Credits
Static analysis part of the code base and a lot of other core ideas are borrowed from damejidlo/message-bus, originally developed by Ondřej Bouda.
All versions of message-bus with dependencies
symfony/messenger Version ^6.4.3@dev || ^7.0.3@dev
psr/container Version ^1.0 || ^2.0
psr/log Version ^1.1 || ^2.0 || ^3.0