README

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

composer require remotelyliving/php-query-bus

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.

$resolver = Resolver::create($serviceContainer) // can locate in service container
    ->pushHandler(GetUserProfileQuery::class, new GetUserProfileHandler()) // can locate in a local map {query => handler}
    ->pushHandlerDeferred(GetUserQuery::class, $lazyCreateMethod); // can locate deferred to save un unnecessary object instantiation

Create the Query Bus

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

$queryBus = QueryBus::create($resolver)
    ->pushMiddleware($myMiddleware1);

$query = new GetUserProfile('id');
$result = $queryBus->handle($query);

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:

class GetUserQuery
{
    private bool $shouldIncludeProfile = false;

    private string $userId;

    public function __construct(string $userId)
    {
        $this->userId = $userId;
    }

    public function getUserId(): string
    {
        return $this->userId;
    }

    public function includeProfile(): self
    {
        $this->shouldIncludeProfile = true;
        return $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:

class GetUserResult extends AbstractResult implements \JsonSerializable
{
    private User $user;

    private ?UserProfile $userProfile;

    public function __construct(User $user, ?UserProfile $userProfile)
    {
        $this->user = $user;
        $this->userProfileResult = $userProfile;
    }

    public function getUser(): User
    {
        return $this->user;
    }

    public function getUserProfile(): ?UserProfile
    {
        return $this->userProfile;
    }

    public function jsonSerialize(): array
    {
        return [
            'user' => $this->getUser(),
            'profile' => $this->getUserProfile(),
        ];
    }
}

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:

class GetUserHandler implements Interfaces\Handler
{
    public function handle(object $query, Interfaces\QueryBus $bus): Interfaces\Result
    {
        try {
            $user = $this->userRepository->getUserById($query->getUserId());
        } catch (ConnectectionError $e) {
            // can handle exceptions without blowing up and instead use messaging via
            // AbstractResult::getErrors(): \Throwable[] and AbstractResult::hasErrors(): bool
            return AbstractResult::withErrors($e);
        }

        
        if (!$user) {
            // can handle nullish cases by returning not found
            return AbstractResult::notFound();
        }
       
        if (!$query->shouldIncludeProfile()) {
            return new GetUserResult($user, null);
        }

        $profileResult = $bus->handle(new GetUserProfileQuery($query->getUserId()));

        return ($profileResult->isNotFound())
            ? new GetUserResult($user, null)
            : new GetUserResult($user, $profileResult->getUserProfile());
    }
}

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:

$cachingMiddleware = function (object $query, callable $next) use ($queryCacher) : Interfaces\Result {
    if ($query instanceof Interfaces\CacheableQuery) {
        return $queryCacher->get($query, function () use ($next, $query) { return $next($query); });
    }
   
    return $next($query);
};

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.

Future Future Development

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

remotelyliving / php-query-bus

Maintainers

Details