Failed Jobs در Laravel — retry، dead letter و عیب‌یابی

Job ایمیل فاکتور fail شد — اگر متوجه نشوید، مشتری فاکتور ندارد و شما نمی‌دانید. Laravel failed jobs را در جدول failed_jobs ذخیره می‌کند — با Horizon UI retry می‌زنید. این مقاله چرخه خطا تا resolution است.

فعال‌سازی ذخیره failed

php artisan queue:failed-table
php artisan migrate

در config/queue معمولاً پیش‌فرض فعال است.

تنظیم retry در Job

public int $tries = 3;
public array $backoff = [10, 60, 300];

public function handle(): void
{
    // ...
}

بعد از tries تمام → failed table.

متد failed

public function failed(?Throwable $exception): void
{
    Log::error('Order confirmation failed', [
        'order_id' => $this->order->id,
        'error' => $exception?->getMessage(),
    ]);
    // notify admin
}

retry دستی

php artisan queue:retry all
php artisan queue:retry 5b2a...
php artisan queue:retry --queue=emails

Horizon: دکمه Retry روی هر failed job.

flush و forget

php artisan queue:flush  # همه failed پاک — با احتیاط
php artisan queue:forget {id}

عیب‌یابی رایج

• API timeout خارجی — timeout job را بالا ببرید
• Model deleted — SerializesModels
• Memory — chunk کار بزرگ
• Bug کد — fix و retry

لاگ در storage/logs + Sentry.

Prune قدیمی‌ها

php artisan queue:prune-failed --hours=168

در Schedule هفتگی.

idempotent jobs

retry باید امن باشد — ارسال دوباره ایمیل بدتر از fail است مگر dedupe داشته باشید.

جمع‌بندی

tries + backoff + failed() + مانیتورینگ. ساخت job: راهنما. مقدمه: Queue.

queue پایدار