PHP Academy · Lesson

Job Retries, Delays, and Chaining

Configure attempts, delays, and chain dependent jobs together.

Job Retries, Delays, and Chaining is a free PHP Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the PHP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Max Attempts

Set how many times a job should be retried before being moved to failed_jobs.

<?php
class SendWelcomeEmail implements ShouldQueue
{
    public int $tries = 3; // retry up to 3 times
}

Max Exceptions

Use $maxExceptions to limit retries based on exception count (unlike attempts which count all tries including timeouts).

<?php
public int $maxExceptions = 3;

Retry After

Set a delay (in seconds) between retry attempts.

<?php
public int $backoff = 60; // wait 60 seconds before retry

// Or exponential backoff:
public function backoff(): array
{
    return [1, 5, 10]; // 1s, 5s, 10s between attempts
}

Job Timeout

Set a maximum execution time in seconds. If the worker exceeds it, the job is released back to the queue.

<?php
public int $timeout = 120; // 2 minutes max

Dispatching with Delay

Delay a job from the dispatch call site.

<?php
SendReminder::dispatch($user)->delay(now()->addDay());
// Or pass a Carbon instance:
SendReminder::dispatch($user)->delay(Carbon::tomorrow());

fail() and released()

Inside handle(), call $this->fail($exception) to immediately mark the job as failed, or $this->release($delay) to re-queue it with a delay.

<?php
public function handle(): void
{
    try {
        // ...
    } catch (TransientException $e) {
        $this->release(30); // re-queue in 30 seconds
    } catch (FatalException $e) {
        $this->fail($e);   // mark as failed now
    }
}

failed() Method

Define a failed() method on the job to run cleanup when all attempts are exhausted.

<?php
public function failed(\Throwable $exception): void
{
    // Notify team, update DB, etc.
    Log::error("Job failed: ".$exception->getMessage());
}

Job Chaining

Chain jobs so each runs only after the previous one succeeds.

<?php
Bus::chain([
    new DownloadFile($url),
    new ProcessFile($path),
    new NotifyUser($user),
])->dispatch();

Caught Chain Failures

Use catch() to handle chain failures without stopping the whole chain.

<?php
Bus::chain([...])
    ->catch(fn (\Throwable $e) => Log::error($e))
    ->dispatch();

Bus::batch()

Dispatch a batch of jobs in parallel and run a callback when all complete or any fail.

<?php
Bus::batch([
    new ImportRow($rows[0]),
    new ImportRow($rows[1]),
])->then(fn ($b) => Log::info("All done"))
  ->catch(fn ($b, $e) => Log::error($e))
  ->dispatch();

Queue Worker Flags

Start workers with specific retry and timeout settings: php artisan queue:work --tries=3 --timeout=90. Job-level settings override worker-level settings.

Summary

Set $tries, $backoff, $timeout on the job. Use release() for temporary failures and fail() for permanent ones. Chain sequential jobs with Bus::chain().

Quick Check

Which method re-queues a job with a delay from inside handle()?

Frequently asked questions

Is the “Job Retries, Delays, and Chaining” lesson free?

Yes — the full text of “Job Retries, Delays, and Chaining” is free to read here on the web, and the PHP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the PHP Academy course, upgrade to CoddyKit PRO.

What will I learn in “Job Retries, Delays, and Chaining”?

Configure attempts, delays, and chain dependent jobs together. You practise PHP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start PHP Academy?

No prior experience is required. PHP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Job Retries, Delays, and Chaining” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this PHP Academy lesson?

Yes. Every PHP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to PHP Academy