Download the PHP package tochka-developers/queue-promises without Composer

Queue Promises

The module allows chaining of Laravel jobs. The promise will be executed after all chained jobs are finished (either completed successfully or failed). The promise has access to job results.

Installation

• Install the package with composer:

• (Laravel 5.4) Register a ServiceProvider in config/app.php

• Publish the configuration:

• Configure the promise storage in config/promises.php.

• Create the promise storage tables:

Usage

Creating a Promise

All promises are derived from Tochka\Queue\Promises\Jobs\Promise. You can create a template promise with artisan:

Class details

The promise class is rather straightforward, as only two methods are needed: success and errors. The success is called by the provider if all chained jobs have completed successfully. The errors is called if any of the jobs failed.

Any of the methods shown above may not be implemented. If a methods is missing it is assumed to do nothing and return true.

Chain Initialization

In order for jobs to attach to a promise they must implement the Tochka\Queue\Promises\Contracts\MayPromised interface. The most common use cases are collected in the Tochka\Queue\Promises\Jobs\Promised trait. You may simply attach these to your class like this:

The chain is constructed by adding any number of jobs to the promise:

After that the promise can be run in one of two modes:

• In synchronous mode all chained jobs will be run sequentially, one at a time, until either one of them fails or all complete successfully. After that, the success or errors of the promise will be executed.
• In asynchronous mode all jobs will be queued immediately, and the promise will wait for them to finish.

The termination conditions can be finely configured via method call:

For convenience, runSync and runAsync may also take the same parameters.

Waiting For Events

Sometimes it is necessary to execute a promise not just after a number of jobs completed, but also when an event is dispatched. Waiting for the events is done with a Tochka\Queue\Promises\Jobs\WaitEvent job:

The constructor of a WaitEvent takes a class of the event to wait for and an unique identifier (of unspecified type). If the identifier is not provided, the WaitEvent will wait for any event of the expected class. If the identifier is given to the constructor, the WaitEvent will complete only when the event with this identifier is dispatched. In order for this to work, the event must implement the Tochka\Queue\Promises\Contracts\PromisedEvent interface:

getUniqueId must return either an identifier or null if no identifier exists.

Note that WaitEvent will never complete if it waits for a class that does not implement the interface.

Promise Timeout

It may be useful at times to execute the promise after a timeout event if some of chained jobs haven't yet finished. This is achieved with a special delayed checker job.

You have to configure the timeout subsystem:

• set the configuration parameter timeout_queue to contain the name of the queue where the checker jobs will be posted. By default the checker jobs are posted to the default queue.
• run a listener for the timeout queue or add it to a list of queues for existing listener.

After that the promises may be set to expire. Two ways of setting a timeout are possible:

• setTimeout($timeout) — the promise will be executed in the given time (in seconds) or after all jobs have completed (whatever happens first).
• setExpiredAt(Carbon $expired_at) — the promise will be executed at the given timestamp (more or less accurately) or after all jobs have completed (whatever happens first).

If the promise times out, the timeout method is called (if defined).

Processing The Results

The getResults method returns the results of all chained jobs:

Job results are returned as classes implementing Tochka\Queue\Promises\Contracts\MayPromised.

Dependency Injection

An alternative way to get the job results is dependency injection versions of generic methods before, success, errors, timeout, and after:

The DI works like follows:

• if a parameter has a type implementing Tochka\Queue\Promises\Contracts\MayPromised, the corresponding result will be injected into this parameter;
• if a parameter has a type implementing Tochka\Queue\Promises\Contracts\PromisedEvent (which is useful when the promise waits for an event), the event itself will be passed as this parameter;
• if there are more than one result of the required class, only the first one will bind;
• if there are more than one parameter of the same class (for example, if the promise waits for several jobs of the same class), the order of results corresponds to the order of the jobs in the chain:

Note that if the promise is run asynchronously, the order of job execution cannot be guaranteed. This may have undesired consequences:

• if there is no appropriate result for a parameter, null is passed;
• if a parameter type does not implement Tochka\Queue\Promises\Contracts\MayPromised, then the value passed to it will be constructed with Laravel DI (like the result of calling app() with the class name).

Tochka\Queue\Promises\Contracts\MayPromised interface declares the following methods: