Jobs + Queue

You are viewing documentation for an unreleased version of Craft CMS. Please be aware that the material is changing frequently and may be incomplete or inaccurate, and links may point back to older versions.

A job in Laravel is generally just a class with a handle() method. Its behavior is determined by a handful of interfaces and traits, which we’ve packaged together for extension as CraftCms\Cms\Queue\Job.

namespace MyOrg\Activity\Reporting\Jobs;

use CraftCms\Cms\Queue\Job;
use MyOrg\Activity\Reporting\Manager;

class GenerateReport extends Job
{
    public function __construct(
        public int $reportId,
        public bool $notifyOwner,
    ) {}

    // Laravel can automatically inject dependencies when it runs your job:
    public function handle(
        Manager $manager,
    ): void
    {
        $report = $manager->getReportById($this->reportId);
    }
}

Push jobs using the dispatch() helper:

dispatch(new GenerateReport(1234, true));

// The base Job class is `Dispatchable`, meaning it has an equivalent static method that forwards arguments to the constructor:
GenerateReport::dispatch(1234, true);

Counterintuitively, jobs are not necessarily queued! When building a custom job, you’ll need to use Illuminate\Contracts\Queue\ShouldQueue and use Illuminate\Queue\InteractsWithQueue; to tell Laravel that it can (and should) be pushed to the queue, rather than executed immediately.

#Priority

Laravel’s queues do not have an equivalent for “priority,” but we allow individual apps to designate a lowPriorityQueue in their general config file. You can divert nonessential jobs to that queue, with the understanding that they may not actually yield to the normal queue. Communicate to developers about your use of the queue so they can plan accordingly.

A few other changes are worth noting: