[12.x] Clarify retryUntil() precedence over tries in queue jobs
#10404
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Laravel allows developers to define a retryUntil() method on queued jobs to specify a time limit for retry attempts. The documentation correctly describes this as an alternative to setting a tries limit.
However, the current text does not clarify what happens when both retryUntil() and tries are defined on the same job. In practice, Laravel prioritizes the retryUntil() constraint, allowing the job to continue retrying until the specified time expires — even if it exceeds the configured number of attempts.
This behavior is handled within the markJobAsFailedIfAlreadyExceedsMaxAttempts()(https://github.com/laravel/framework/blob/12.x/src/Illuminate/Queue/Worker.php) method, where the retryUntil() timestamp is checked before enforcing the maxTries logic.
This PR proposes the following note to be added to the documentation, immediately after the current explanation of retryUntil():
If both retryUntil and a tries limit are defined, Laravel will prioritize the retryUntil method. This means the job may be attempted multiple times until the given time expires, even if the configured tries limit is exceeded.
I believe this clarification will help avoid confusion for developers who define both constraints, expecting both to apply simultaneously.
Please let me know if you'd prefer a different placement or phrasing.