Download the PHP package remotelyliving/php-query-bus without Composer

php-query-bus: 🚍 A Query Bus Implementation For PHP 🚍

Use Cases

If you want a light weight compliment to your Command Bus for CQRS, hopefully this library helps out. It's very similar to a Command Bus, but it returns a Result.

I've used magical data loading solutions before, but good old fashioned set of specific Query, Result, and Handler objects for a given Use Case is generally more performant, predictable, and explicit than magic-based implementations.

Installation

Usage

Create the Query Resolver

The resolver can have handlers added manually or locate them in a PSR-11 Service Container Queries are mapped 1:1 with a handler and are mapped by the Query class name as the lookup key.

Create the Query Bus

The Query Bus takes in a Query Resolver and pushes whatever Middleware you want on the stack.

Middleware is any callable that returns a Result. Some base middleware is included: src/Middleware

That's really all there is to it!

Query

The Query for this library is left intentionally unimplemented. It is just an object. My suggestion for Query objects is to keep them as a DTO of what you need to query your data source by.

An example query might look like this:

As you can see, it's just a few getters and option builder.

Result

The Result is similarly unimplemented except for the provided AbstractResult. Results can have their own custom getters for your use case. An example Result for the GetUserQuery above might look like:

As you can see, it's not too hard to start building Result graphs for outputting a response or to feed another part of your app.

Handler

The handlers are where the magic happens. Inject what ever repository, API Client, or ORM you need to load data. It will ask the query for query parameters and return a result. You can also request other query results inside a handler from the bus. Going with our GetUserQuery example, a Handler could look like:

Middleware

There are a few Middleware that this library ships with. The default execution order is LIFO and the signature very simple.

A Middleware must return an instance of Result and be callable. That's it!

An example Middleware could be as simple as this:

QueryCacher

This middleware provides some interesting query caching by utilizing Probabilistic Early Cache Expiry to help prevent cache stampedes. To be cached, a Query must implement the CacheableQuery interface. To recompute cache simply fire off a Query with the value of CacheableQuery::shouldRecomputeResult() returning true.

QueryLogger

Helpful for debugging, but best left for dev and stage environments. Looks for the LoggableQuery marker interface on the query

ResultErrorLogger

Helpful for debugging and alerting based on your logging setup.

PerfBudgetLogger

Allows you to set certain rough performance thresholds and log with something has gone over that threshold.

Future Future Development

• Result Filtering (should be done at a query level, but would be nice to be able to specify sparse field sets