Allow per-job opt-out from failed_jobs persistence

[hien11dev]

Add a way to control failed_jobs persistence on a per-job basis, without touching the global queue.failer configuration.

Problem

Currently, whether a failed job gets persisted to failed_jobs is controlled entirely at the global level (via the queue.failer driver). There's no way to opt a specific job out of failure logging while still keeping:

• normal retry behavior
• the failed() method being called
• the JobFailed event being dispatched

This matters for jobs where failure is expected/non-critical (e.g. best-effort notifications, non-essential sync tasks) and don't need to be tracked in failed_jobs, while other jobs in the same application still need standard failure persistence.

Proposed API

A method on the job class, e.g.:

class ProcessTranslationJob implements ShouldQueue
{
    public function shouldStoreFailedJob(): bool
    {
        return false;
    }

    public function failed(?Throwable $exception): void
    {
        // business-level failure handling
    }
}

Jobs that don't define this method keep the current default behavior (stored in failed_jobs).

An interface-based alternative may fit Laravel's conventions better:

interface ShouldNotPersistFailure
{
    //
}

Or a PHP attribute, consistent with existing job attributes like #[WithoutOverlapping]:

#[WithoutFailedJobLog]
class ProcessTranslationJob implements ShouldQueue
{
    //
}

Where this should live

Rather than patching WorkCommand::logFailedJob() — which only covers one entrypoint — this should be handled in Illuminate\Queue\Worker::failJob(), so the behavior is consistent across queue:work, queue:listen, Horizon, and any custom worker implementation.

Rough sketch:

protected function failJob($job, $connectionName, $e)
{
    // ... existing failed() call + event dispatch ...

    if ($job instanceof ShouldNotPersistFailure) {
        return;
    }

    $this->laravel['queue.failer']->log(
        $connectionName,
        $job->getQueue(),
        $job->getRawBody(),
        $e
    );
}

Note: $event->job in JobFailed is the queue wrapper (DatabaseJob, SqsJob, etc.), not the unwrapped job instance — the check needs to happen against the resolved job object, not the wrapper.

Expected behavior

Job with shouldStoreFailedJob() returning false (or implementing the opt-out interface/attribute):

• retries work normally
• failed() is called
• JobFailed is dispatched
• job is not inserted into failed_jobs

All other jobs (default, unchanged):

• failed() is called
• JobFailed is dispatched
• job is inserted into failed_jobs

Why not just use a custom failed_jobs provider?

Because the choice is per-job, not per-application. Switching the failer driver or writing a custom one still applies globally — it can't distinguish "this job's failure matters" from "this job's failure doesn't," which is the actual problem being solved here.

Open questions

• Method vs. interface vs. attribute — which fits Laravel's current conventions best?
• Should this also affect Bus::dispatchAfterResponse() sync-fallback paths, or only the queue worker flow?
• Naming: shouldStoreFailedJob(), ShouldNotPersistFailure, #[WithoutFailedJobLog] — open to suggestions.

Happy to follow up with a PR (including tests against Worker::failJob()) if this direction seems acceptable.

[henzeb]

And why is error handling and gracefully successfully ending the job not a solution?

[hien11dev]

Handling the error and letting the job end successfully isn't a solution here, because tries, backoff, and maxExceptions only work when the job actually throws and lets the worker handle it. If you catch the exception yourself inside handle() so the job ends gracefully, the job is treated as successful on the first run you lose retries, backoff, and maxExceptions entirely, and would have to reimplement that retry logic manually, which is redundant and easy to get wrong compared to what the framework already handles.

What I actually want is for the job to still throw, still fail for real, and still go through tries/backoff/maxExceptions exactly as normal I just want to customize how the failure gets logged (or skip failed_jobs) for a few specific jobs, without touching that retry pipeline.

[wasifahmed85]

Right now, when a job fails permanently, Laravel writes it to the failed_jobs table globally (config-level queue.failed.driver) — there's no per-job way to say "don't persist this one" (e.g., for noisy/low-value jobs, PII-sensitive jobs, or jobs you already log elsewhere).

Suggested solution:

Add a job-level opt-out, similar to how $tries, $backoff, etc. work:

php
class SendAnalyticsPing implements ShouldQueue
{
public bool $storeFailedJob = false; // opt out of failed_jobs persistence
}

Or as a method-based override for more control:

php
public function shouldStoreFailure(): bool
{
return false;
}

Where it'd hook in: CallQueuedHandler/Worker::handleJobException() currently unconditionally calls FailedJobProviderInterface::log() when a job exhausts retries. This would just need a check before that call:

php
if ($job->shouldStoreFailure() ?? true) {
$this->failer->log(...);
}

Why it's useful:

Avoids failed_jobs table bloat from expected/low-priority failures (e.g., best-effort notifications).
Lets teams keep sensitive payloads out of persistent storage while still using failed() callbacks or custom logging for those jobs.
Non-breaking — defaults to current behavior (true).

This fits naturally alongside existing per-job properties, so it's a low-risk, additive change rather than a new subsystem.