Job Queue

Aurora boasts a Job queue that allows you to run certain time-consuming tasks in a secondary process worker.

For example, say you have a recover password page in your application. Sending an email can take its time and if you don't want to make the user wait you can just add a 'SendRecoveryEmailJob' to the queue and tell the user that the mail is on its way. For that to work properly, you must have one or several background worker processes to run any pending jobs, so that when you add the job the queue one of these workers take the job order and send the mail.

To enable the Queue on your application you must set it up first:

php aurora queue:setup

That will tell the queue adapter to create its required tables, files, etc. that will be used to keep track of the pending jobs.

Now it's time to create the Job class, to do so you'll need to run:

php aurora create:job SendRecoveryEmailJob

Which will create a file named SendRecoveryEmailJob on your app/Jobs directory with the following structure:

<?php

namespace App\Jobs;

use Aurora\Queue\AbstractJob;

class SendRecoveryEmailJob extends AbstractJob {

    /**
     * The handler function, must be implemented
     * @return void
     */
    public function handle(): void {
        # Add your job logic here
        $app = app();
        $app->success('Job succeeded');
        $this->complete();
    }
}

In its simplest form, a Job does a task and calls its completed method to mark the job as done and remove it from the queue.

For example, we have the following logic for our recovery mail sender:

use App\Services\MailSender;

...

protected $max_retries = 3;

public function handle(): void {
    $console = resolve(Console::class);
    $sender = resolve(MailSender::class);
    $success = $sender->send('recovery', $this->data);
    if ( $success ) {
        $console->success('Mail sent successfully');
        $this->complete();
    } else {
        if ( $this->retries < $this->max_retries ) {
            $console->warning([$this->retries + 1, $this->max_retries], 'Error sending mail, retrying (%d/%d)...');
            $this->retry();
        } else {
            $console->error('Error sending mail, no more retries');
            $this->failed();
        }
    }
}

For this example, we used a mock service named MailSender that has a send method which returns true or false depending on whether the mail has been sent or not. We take that result and check it, on success the Job is simply marked as complete, but on failure we retry the job up to 3 times, after which we mark the job as failed.

It is not required to retry a job, but sometimes may be a good practice to try again a couple times.

Adding jobs to the queue

Now that we've created our job class we can use it to enqueue jobs.

Doing so is easy, say that you have a controller where you process your password recovery form:

use Aurora\Queue\Queue;
use App\Database\Models\User;
use App\Jobs\SendRecoveryEmailJob;

...

class UtilitiesController extends Controller {

    public function recoverGet(ServerRequestInterface $request, ResponseInterface $response) {
        $content = view('page-recover')->render();
        $response->getBody()->write($content);
    }

    public function recoverPost(ServerRequestInterface $request, ResponseInterface $response) {
        # Get the form data and validate the user
        $fields = $request->getParsedBody();
        $email = $fields['email'] ?? '';
        $user = $email ? User::getBy('email', $email) : null;
        if ($user) {
            $queue = resolve(Queue::class);
            $queue->add(SendRecoveryEmailJob::class, ['user' => $user]);
        }
        # Redirect
        redirect( base_url('/recover?msg=MSG_EMAIL_SENT') );
    }
}

The important bit is:

$queue = resolve(Queue::class);
$queue->add(SendRecoveryEmailJob::class, ['user' => $user]);

Basically you get a reference to the Queue service and just add a new job using your job class, passing some data if required.

Running the job queue

Now that you've added some jobs to the queue we need to start working on them, and for that you can have one, two or serveral workers running the pending jobs in parallel. To do so there are multiple options, for example by using a CRON job to start the workers or by using a tool like Supervisor to keep track of your worker processes.

Whatever option you choose you must run the following command to start the queue work:

php aurora queue:work

That command will take a job from the pending queue, work on it and move on to the next one. Also if there are no jobs currently in the queue, it will wait for them to start arriving.

As we said before, you can have several workers to dispatch your pending jobs quickly.

Resetting jobs

You can use the queue:reset command to mark failed and stalled jobs as pending to rety them, just run:

php aurora queue:reset

Optionally you can specify the job class, for example:

php aurora queue:reset SendRecoveryEmailJob

Purging the queue

Another option is to just discard failed jobs, you can do so with the queue:purge command:

php aurora queue:purge

Again, you may specify the job class, for example:

php aurora queue:purge SendRecoveryEmailJob

Next up, Storage.