[12.x] Add defer method to PendingDispatch

[bram-pkg]

This PR adds support for dispatching a job like:

dispatch(new MyJob())->defer();

Which wouldn't put the job on the queue until after the request, command or job is finished.
Under the hood, Laravel's defer() function is used. We've had a dispatch_defer method in our codebase for a while now, and I think other people could benefit from this.

I've also written some tests for the dispatch logic.

[github-actions]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[timacdonald]

My main concern with this is that it is different to the afterResponse method, which feels unexpected. That being said, anecdotally I feel like the afterResponse method is misunderstood by people.

dispatch(MyJob::class)->afterResponse();

indicates that the job should be executed synchronously during the HTTP request, not on the queue, but after the response has been sent.

e.g., it is the same as:

App::terminating(fn () => MyJob::dispatchSync()); // execute the job synchronously after response has been sent

afterResponse seems to trip people up because they think it means "dispatch this job to the queue after the response has been sent", e.g.,

App::terminating(fn () => MyJob::dispatch()); // dispatch to queue after response sent

Adding defer to the mix might confuse that further, especially given this implementation works differently.

I wonder if composition is the best way forward here. It makes it unambiguous as to what is happening.

// Dispatch to the queue after the execution has completed.
defer(fn () => MyJob::dispatch());

// Execute the job synchronously the execution has completed.
defer(fn () => MyJob::dispatchSync());

[bram-pkg]

Hi Tim,

Yes, when I polled people in our engineering team most people did think afterResponse functions like your second code snippet, where it dispatches to the queue after the response.

Happy to keep this as an internal helper for our team, but I was hoping that this would bring attention to this unclear functionality to more people and perhaps save people investigating their flame charts.

Misusing afterResponse makes our response times look much slower for example. It's only when you dig in that it's obvious that the response has already been sent halfway through the graph.

[bram-pkg]

As for the tests, they have proven to be a bit tricky. Not sure if I'm doing something wrong, but intuitively it feels like they "should" work in their current state, but they don't.