Download the PHP package icanboogie/message-bus without Composer
On this page you can find all versions of the php package icanboogie/message-bus. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download icanboogie/message-bus
More information about icanboogie/message-bus
Files in icanboogie/message-bus
Package message-bus
Short Description A straightforward implementation of a message dispatcher
License BSD-3-Clause
Homepage https://icanboogie.org/
Informations about the package message-bus
MessageBus
A message dispatcher helps to separate presentation concerns from business logic by mapping inputs of various sources to simpler application messages. It also helps to decouple the domain from the implementation, for an application only has to know about the messages, not how they are handled. A design well known in Hexagonal architectures.
ICanBoogie/MessageBus provides an implementation of a message dispatcher, with support for permissions and voters. There's also a simple implementation of a message handler provider, and one more sophisticated that works with PSR-11 containers. Finally, there's special support for Symfony's Dependency Injection component.
Using a message dispatcher can be as simple as the following example:
Installation
If you're upgrading to a newer version, please check the Migration guide.
Messages
Messages can be any type of object. What's important is that all input type considerations (e.g. HTTP details) are removed to keep what's essential for the domain. That is, a controller would create a message to dispatch, but controller concern would stay in the controller, they would not leak into the message.
The following example demonstrates how a DeleteMenu
message could be defined. Note that there
isn't a notion of input type or authorization. These are presentation concerns, and they should
remain there.
Messages that don't alter the state of an application—in other words, messages that lead to
read-only operations—can be marked with the Safe
interface. This is not a requirement, just a
recommendation to help you identify messages.
Message handlers
Message handlers handle messages. Usually the relation is 1:1, that is one handler for one message
type. Message handlers are callables, typically a class implementing __invoke(T $message)
, where
T
is a type of message.
The following example demonstrates how a handler can be defined for a ShowMenu
message:
Providing message handlers
Message handlers are obtained through a provider, usually backed by a service container.
The following example demonstrates how to obtain a message handler for a given message, and how to invoke that handler to get a result.
Providing handlers with a PSR container
Handlers can be provided by an instance of PSR\HandlerProviderWithContainer, which is backed by a PSR container. You need to provide the mapping from "message class" to "handler service identifier".
Providing handlers with Symfony's Dependency Injection component
The easiest way to define messages, handlers, permissions, and voters, is with Symfony's Dependency Injection component. The handlers are defined as services, tags are used to identify them and the message type they support. It's also possible to define permissions, and voter for those permissions.
You can use the services.yaml
file provided directly in your project, together with the
compiler pass MessageBusPass.
The following example demonstrates how to define handlers, commands, permission, and voters:
Using PHP 8 attributes instead of YAML
With the composer-attribute-collector Composer plugin, PHP 8 attributes can be used instead of YAML to define handlers, permissions, and voters.
For handlers and permissions, the Handler and Permission attributes can be used to replace YAML:
For voters, the Vote attribute can be used to replace YAML:
You just need to add the compiler pass MessagePubPassWithAttributes before MessageBusPass:
Providing handlers using a chain of providers
With HandlerProviderWithChain
you can chain multiple handler providers together. They will be used
in sequence until a handler is found.
Permissions and voters
You probably want to restrict the dispatch of messages to certain conditions. For example, deleting records should only be possible for users having a certain scope in their JWT. For this, you want to make sure of a few things:
-
Define voters and the permission they vote for.
-
Tag the permissions together with the handler and message definition.
-
Require a Dispatcher.
- Put in the context whatever is required for the voters to make their decision. In the following example, that would be a token, for the voter to check for scopes.
Continuous Integration
The project is continuously tested by GitHub actions.
Code of Conduct
This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you are expected to uphold this code.
Contributing
Please see CONTRIBUTING for details.
License
icanboogie/message-bus is released under the BSD-3-Clause.