[11.x] Introduce throw() to PendingDispatch

[tiramisuliu]

This pull request introduces an optional feature to throw an exception when attempting to dispatch a subsequent unique job that is already in the queue. This enhancement provides clear feedback to the job dispatcher, indicating that the current dispatch attempt has been ignored due to the presence of an existing unique job.

Details:

• Adds an option to throw JobDispatchedException if a unique job with the same identifier is already dispatched.
• Allows PendingDispatch to register a callback to be called right before the exception is about to be thrown - similar to the throw() behavior from the HTTP Client/Response and the Process Facade.

Example Usage:

An exception is thrown if the job fails to meet the "unique" requirement.

UpdateSearchIndex::dispatch()
    ->throw();

The closure is executed immediately before the exception is thrown.

UpdateSearchIndex::dispatch()
    ->throw(function () {
    });

The existing behavior of ignoring subsequent dispatches of the same unique job is preserved.

UpdateSearchIndex::dispatch();

Note:

I'm currently having trouble instantiating an instance of Illuminate\Contracts\Cache\Repository in the test - appreciate any pointers!

[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.

[hn-seoai]

For consistency with similar functionality in batches/chains, wouldn't catch(callable $callback) be a better name?

[shaedrich]

I don't like the quite broad naming. Wouldn't it be better to have something like throwOnDuplicates() or the like?

Another possible parameter (type) to this method could be a class-string indicating an alternative exception to throw as syntactic sugar to throwing it oneself within a callback.