Introduction

Lately, as I'm working a lot with Laravel's command bus, I started noticing that most mutation resolvers in codebases I'm working on merely dispatch a job onto the command bus (as validation and authorization can all be done through existing Lighthouse directives). Unless I missed something, you currently have to create a custom resolver in order to dispatch a job on the command bus. For example:

namespace App\GraphQL\Mutation;
use App\Jobs\ProcessPodcast as ProcessPodcastJob;
use App\Models\Podcast;
use Illuminate\Contracts\Bus\Dispatcher;
use Nuwave\Lighthouse\Support\Contracts\GraphQLContext;
final readonly class ProcessPodcast 
{
 public function __construct(
 private Dispatcher $bus,
 ) {}
 public function __invoke(null $root, array $args, GraphQLContext $context): Podcast
 {
 return $this->bus->dispatch(new ProcessPodcastJob($args['podcast']));
 }
}

This leads me to wonder if it could be interesting to have a Lighthouse directive to directly map mutations to a job from within the schema definition.

Proposal

I would propose to introduce a new @bus directive with a similar setup to the @event directive:

"""
Dispatch a (queued) job using the Laravel Command Bus.
"""
directive @bus(
 """
 FQCN for the job to dispatch.
 """
 dispatch: String!
 
 """
 Dispatch a job immediately (synchronously). The job will not be queued
 and will be executed immediately within the current process.
 """
 sync: Boolean! = false
 
 """
 Set the pipes using FQCNs the job should be piped through before dispatching.
 """
 pipeThrough: [String!]! = []
) on FIELD_DEFINITION

With this specification, the example in the introduction could be implemented as follows:

type Mutation {
 processPodcast(podcast: ID!): Podcast @bus(dispatch: "App\\Jobs\\ProcessPodcast")
}

Forcing sync dispatch

By default, jobs would be dispatched through Illuminate\Contracts\Bus\Dispatcher::dispatch(), which inspects the job to determine whether the job should be queued or not. However, the async argument on the @bus directive would allow developers to force dispatching a job synchronously by using Illuminate\Contracts\Bus\Dispatcher::dispatchSync()instead.

type Mutation {
 processPodcast(podcast: ID!): Podcast @bus(dispatch: "App\\Jobs\\ProcessPodcast", sync: true)
}

Manipulating jobs before or after dispatch

Laravel's command bus allows developers to define pipes to pass a job through upon dispatch. These pipes basically behave like middleware, meaning jobs can be manipulated before or after dispatch. This could be useful to allow for example formatting the directive's return value in order to match the schema definition:

type Mutation {
 processPodcast(podcast: ID!): Podcast @bus(
 dispatch: "App\\Jobs\\ProcessPodcast"
 pipeThrough: [
 "App\\GraphQL\\Mutation\\WrapJobResult",
 ]
 )
}

Breaking changes

As this would introduce a new directive, no breaking changes should be made to implement this idea.

Implementation

I haven't developed this yet, but are willing to do so if there's any interest. This is merely a basic proposal, any suggestions to improve or extend the idea are welcome.