Scheduler

The Scheduler provides a robust background job processing system, allowing you to defer time-consuming tasks and execute them asynchronously. It mirrors the ergonomics of popular queue systems, making it easy to offload work such as sending emails, processing payments, or generating reports.

Introduction

The Scheduler allows you to create job classes that contain the logic you want to execute in the background. Jobs are stored in the database and processed by a worker that runs via WordPress cron. You can control the priority, delay execution, and configure retries for failed jobs.

Defining Jobs

To create a job, you need to define a class that uses the Queueable trait and implements a handle method.

Job Class Structure

Define the structure of a job class.

Description:

A job class must use the Queueable trait to gain access to dispatching and configuration methods. The core logic of the job resides in the handle method, which receives the arguments passed during dispatch.

Method Signature:

public function handle(array $args): void

Parameters:

• $args - An array of arguments passed to the job when dispatched.

Examples:

<?php

namespace Override\Jobs;

use Ecommerce\Core\Scheduler\Concerns\Queueable;
use Ecommerce\Core\Scheduler\Contracts\ShouldQueue;
use Ecommerce\App\Models\Order;

class ProcessOrderJob implements ShouldQueue
{
    use Queueable;

    // Optional: Configure retries
    protected $retry = 3;

    public function handle(array $args)
    {
        $order_id = $args['order_id'];
        $order = Order::find($order_id);

        if ($order) {
            // Process the order...
            error_log("Processing order: " . $order->id);
        }
    }
}

// Simple email job
class SendEmailJob
{
    use Queueable;

    public function handle(array $args)
    {
        $to = $args['to'];
        $subject = $args['subject'];

        wp_mail($to, $subject, 'Email content...');
    }
}

---

Dispatching Jobs

Once a job is defined, you can dispatch it for execution.

Dispatch

Dispatch a job to be processed by the background worker.

Description:

The dispatch() method creates a new instance of the job and pushes it to the scheduler queue. You can pass arguments to the method, which will be available in the handle method of the job.

Method Signature:

public static function dispatch(mixed ...$arguments): DeferredDispatcher

Parameters:

• ...$arguments - Arguments to pass to the job. Can be a single array or multiple arguments.

Examples:

use Override\Jobs\ProcessOrderJob;
use Override\Jobs\SendEmailJob;

// Dispatch with a single array argument
ProcessOrderJob::dispatch(['order_id' => 123]);

// Dispatch with multiple arguments (received as an array in handle)
// If handle expects ['to' => ..., 'subject' => ...] make sure to pass an array
SendEmailJob::dispatch(['to' => 'user@example.com', 'subject' => 'Welcome!']);

---

Delayed Dispatching

You can specify that a job should not be processed until a specific time.

Delay Execution

Delay the execution of a job by a given time or interval.

Description:

The delay() method allows you to schedule a job for future execution. The job will be stored in the database but will not be picked up by the worker until the scheduled time is reached.

Method Signature:

public function delay(int|string|\DateTime $moment): self

Parameters:

• $moment - A DateTime instance, a string parseable by strtotime, or a timestamp.

Examples:

use Override\Jobs\ProcessOrderJob;
use Ecommerce\Supports\Facades\Date;

// Delay for 10 minutes
ProcessOrderJob::dispatch(['order_id' => 123])
    ->delay(Date::now()->add_minutes(10));

// Delay until a specific date
ProcessOrderJob::dispatch(['order_id' => 456])
    ->delay('2026-02-01 00:00:00');

---

Job Configuration

You can configure various properties of the job to control its execution behavior.

Set Priority

Set the priority level of the job.

Description:

The priority() method sets the execution priority of the job. Lower numbers indicate higher priority (e.g., 1 is higher priority than 10). The worker picks up higher priority jobs first. Default priority is 10.

Method Signature:

public function priority(int $priority): self

Parameters:

• $priority - The priority level (0-255).

Examples:

// High priority job
ProcessOrderJob::dispatch(['order_id' => 123])->priority(1);

// Low priority job
ProcessOrderJob::dispatch(['order_id' => 456])->priority(20);

---

Retry Configuration

Configure the number of times a job should be retried if it fails.

Description:

You can define the $retry property on the job class to specify how many times the scheduler should attempt to run the job if it throws an exception.

Examples:

class ProcessPaymentJob
{
    use Queueable;

    // Retry this job 3 times if it fails
    protected $retry = 3;

    public function handle($args)
    {
        // ... payment logic that might fail ...
    }
}

Note: If the job fails (throws an exception), the scheduler catches it, increments the attempt counter, and schedules it for retry (usually in the next batch) until the max retry count is reached.

---

Batch Size

Configure the batch size for the job.

Description:

The $batch property allows you to control how many instances of this job can be claimed by a single worker process at once.

Examples:

class ImportDataJob
{
    use Queueable;

    // Process 50 of these jobs in one go
    protected $batch = 50;

    public function handle($args)
    {
        // ...
    }
}