Download the PHP package awd-studio/service-buses without Composer

Service buses in PHP

A simple library, to implement CQRS-ish pattern on PHP projects.

Features:

• Neither messages nor handlers don't need to extend or implement any additional abstraction.
• A handler can be any of callable items.
• Handlers can subscribe on any of parents or implementations of an event.
• Contains a decorator to register handles as services handled via PSR-11's container.
• Contains a decorator to auto-subscribe handlers by a typehint on a message that it handles.
• Provides ready to go bus patterns such a Command Bus, a Query Bus and an Event Bus implementations.

Contents:

• Get started
• Handling messages
• Predefined buses
  • Command Bus
  • Query Bus
  • Event Bus
• Subscribe on parents
• Services as handlers
  • Auto-register services
  • Using your own handling methods
• Define custom bus
• Testing

Get started:

Requirenments:

• PHP 8.2+
• PSR-11 - compatible container (optional)

Install:

Handling messages:

A message, is nothing, but a simple PHP-object.

It can contain any data you need, but usually, it's better to provide some immutable messages, that can be serialized.

Anyway, you are able to extend or implement anything you need.

A handler-locator is a repository for handlers.

With them, we can assign a handler to particular messages. Library provides some handler locators, for example - a locator to store handlers in memory:

To handle a message, the bus needs to be called. For instance, we have a bus that extends provided SimpleBus.

We're gonna use a

Predefined buses:

There are a few predefined buses:

• \AwdStudio\Command\CommandBus (The Command-bus pattern akka C in CQRS)

  • \AwdStudio\Command\SimpleCommandBus - Handles a command, via single handler.

• \AwdStudio\Query\QueryBus (The Query-bus pattern akka Q in CQRS)

  • \AwdStudio\Query\SimpleQueryBus - Handles a query, via single handler.
• \AwdStudio\Event\EventBus (Observer-subscriber pattern)
  • \AwdStudio\Event\SimpleEventBus - Dispatches an event, to each subscriber (can be >= 0).

Command-bus:

Query-bus:

Event-bus:

Subscribe on parents

The library allows subscribing not only on a certain class, but on all of its parents - either a parent or an implementation from any level.

Services as handlers

Of course, to resolve the only callbacks as handlers is not such a convenient way to build projects. Fortunately, we have standards as a PSR-11 for such common use-cases as implementation of DIP. And, the library provides ability to use those containers as service locators for resolving handlers as DI.

To use it, there is a decorator for a handler-locator, that can be used for registering handlers with just FCQN. As a dependency it accepts any of Psr\Container\ContainerInterface, that supposed to resolve handlers.

Auto-register services

There is even a decorator to subscribe callbacks automatically, by their signature, that supposed to contain a type-hint as the very first parameter.

Using your own handling methods

If you don't like invokable services, or somehow need to use handlers that handle via different methods - this is not a problem at all.

Just pass the name of a method while registering:

Define custom bus

To define your own bus, you can extend one of predefined ones. You have 2 options:

The SimpleBus provides you an ability to handle messages with only handles.

Testing: