About

This PR is based on a recent post I shared on X, where I discussed some pain points around Horizon.

I did my best to avoid injecting strong personal opinions or turning the documentation into a blog post.

Queues:

Clarifies how job attempts are counted and how failed jobs are handled. Adds updated examples and notes for middleware and retries.

Horizon:

Adds sections on queue priorities, job attempts, timeouts, and backoff. Improves explanations for environment configuration and worker balancing.

There are still options left to document.

Reflections on maxException and tries Defaults

While working on this PR, I strongly felt the need for an option to configure maxExceptions at the Horizon supervisor or queue worker level, similar to how tries can currently be set.

Additionally, I’m wondering whether the default value for tries is appropriate. Many of Laravel’s advanced queue features, such as WithoutOverlapping and RateLimited, often require increasing the tries value significantly, sometimes even setting it to 0.

In my opinion, the default configuration should be more aligned with these common use cases. A more sensible default might look like:

• tries: 25
• maxException: 1

This defaults would work better out of the box for most Laravel developers .