Defining & Dispatching Jobs
Learn how to write queueable job classes and dispatch them in your application.
Defining Jobs
Jobs implement Jengo\Queues\Contracts\ShouldQueue and use the Queueable and InteractsWithQueue traits.
Create a new job class under app/Jobs/:
<?php
namespace App\Jobs;
use Jengo\Queues\Contracts\ShouldQueue;
use Jengo\Queues\Traits\InteractsWithQueue;
use Jengo\Queues\Traits\Queueable;
use Throwable;
class SendWelcomeEmail implements ShouldQueue
{
use Queueable;
use InteractsWithQueue;
/**
* Max retry attempts before failing.
*/
public int $tries = 3;
/**
* Timeout in seconds.
*/
public int $timeout = 60;
/**
* Delay in seconds between retries.
*/
public int $backoff = 10;
public function __construct(public int $userId, public string $email)
{
}
/**
* Execute the job.
*/
public function handle(): void
{
// Perform the task
log_message('info', "Sending welcome email to user {$this->userId} ({$this->email})...");
}
/**
* Handle a job failure.
*/
public function failed(Throwable $exception): void
{
log_message('error', "Failed to send welcome email: {$exception->getMessage()}");
}
}Serialization Best Practices
When dispatching jobs into asynchronous drivers (such as database or redis), PHP serializes the entire job object into a payload string. To ensure reliability and avoid stale data:
1. Pass Identifiers, Not Active Models
Never serialize full database entity instances, open PDO connections, or resource streams. Pass IDs and reload entities inside handle():
// Recommended: Pass scalar IDs
public function __construct(public int $orderId) {}
public function handle(): void
{
$orderModel = model(OrderModel::class);
$order = $orderModel->find($this->orderId);
if (! $order) {
// Record was deleted prior to worker execution
return;
}
// Process order...
}2. Avoid Heavy Closures or Circular References
Job constructors should avoid closures or classes referencing large application services, since un-serializable dependencies will trigger a SerializationException. Ensure all properties are serializable PHP types.
Dispatching Jobs
1. Using the dispatch() Helper
use App\Jobs\SendWelcomeEmail;
// Dispatch immediately to default queue
dispatch(new SendWelcomeEmail(10, 'user@example.com'));
// Dispatch with delay
dispatch_later(60, new SendWelcomeEmail(10, 'user@example.com'));2. Fluent Dispatch from Job Instance
(new SendWelcomeEmail(10, 'user@example.com'))
->onQueue('emails')
->onConnection('redis')
->delay(120)
->tries(5)
->backoff(30)
->dispatch();3. Using the Queue Facade
use Jengo\Queues\Facades\Queue;
// Push to default connection
Queue::push(new SendWelcomeEmail(10, 'user@example.com'));
// Push to specific queue on specific connection
Queue::connection('redis')->push(new SendWelcomeEmail(10, 'user@example.com'), '', 'emails');
// Push with delay
Queue::later(300, new SendWelcomeEmail(10, 'user@example.com'));Job Lifecycle Controls
Inside your job's handle() method, you can interact with the current job execution context:
public function handle(): void
{
if ($this->attempts() > 2) {
log_message('warning', "Job attempt {$this->attempts()} running...");
}
if ($someCondition) {
// Release job back to queue with 60s delay
$this->release(60);
return;
}
// Delete job manually if needed
$this->delete();
}