Laravel Queue Worker Laravel Package

Getting Started

Start with the upgrade path and timeout contract, because this release changes how jobs behave at runtime:

1. In every environment, require "jeffersongoncalves/laravel-queue-consumer": "^1.2". Do not rely on ^1.1; an existing composer.lock may still hold 1.1.x.
2. Check the hub queue connection’s retry_after. It must be greater than the longest environment timeout plus 60 seconds.
3. Read the README’s timeout-ordering section before sending jobs with non-default timeouts.
4. Send your first job through POST /api/jobs with an explicit timeout and verify it appears correctly in failed_jobs when the child environment times out.

The first useful use case is a long-running job that previously failed at 60 seconds. After upgrading, the payload timeout is passed to the child process, and the hub job keeps that timeout plus a 60-second margin so the child process is killed by Symfony before the worker alarm fires.

Implementation Patterns

• Declare realistic per-job timeouts in the payload. The child process now receives the payload timeout instead of Laravel’s PendingProcess default of 60 seconds.
• Keep hub and environment versions aligned. The hub passes --queue; consumers on laravel-queue-consumer 1.1.0 fail with The "--queue" option does not exist.
• Treat timeout validation as part of your API contract. A payload with timeout: 0 or a negative timeout is rejected with 422. A timeout whose value plus the 60-second margin reaches retry_after is also rejected with 422, and the error names both numbers.
• Size retry_after from the largest timeout any environment can declare, not from the hub job’s own runtime. The rule is: longest environment timeout + 60 seconds < retry_after.
• Catch OutdatedEnvironmentConsumerException when surfacing job failures. It includes the environment slug, its path, and the exact composer require jeffersongoncalves/laravel-queue-consumer:^1.2 command to run there.
• Monitor failed_jobs after rollout. With the new timeout ordering, a child timeout should produce a failed row naming the environment rather than killing the worker and orphaning the child process.
• For jobs queued before the upgrade, expect the 60-second margin to come out of the child’s share. The worker alarm reads the timeout from the already-queued outer payload, which cannot be rewritten in Redis.

Gotchas and Tips

• ^1.1 is not enough. It allows 1.2.0 but does not require it, and an existing lock file can keep an older 1.1.x resolved. Update and redeploy each environment explicitly.
• retry_after validation is a preflight gate. If it is too low, affected jobs are refused at POST /api/jobs with 422 instead of being accepted and run twice concurrently.
• timeout: 0 is not “unlimited” here. Laravel treats it as “no timeout,” but this package rejects it with 422, as it does negative timeouts.
• The outdated-consumer detection matches only the child’s stderr. A job whose own output quotes The "--queue" option does not exist. should not be mistaken for an outdated consumer.
• The 60-second margin is deliberate: the child should time out first. If you see worker-level alarms or orphaned children, check whether the payload timeout and retry_after ordering are correct.
• The most useful debugging surfaces are the 422 response body from POST /api/jobs, the environment slug/path in OutdatedEnvironmentConsumerException, the hub queue connection’s retry_after, and the failed_jobs row for the environment.
• The README documents the full timeout ordering; use it as the source of truth when changing queue connection settings or environment timeouts.