From 48b5102b4c9ca0bbd5ccbf8d1c841cd0b6876298 Mon Sep 17 00:00:00 2001
From: Luke Kuzmish <42181698+cosmastech@users.noreply.github.com>
Date: Tue, 17 Jun 2025 14:27:10 -0400
Subject: [PATCH 1/5] FailOnException middleware

---
 queues.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/queues.md b/queues.md
index 94a48954b05..8adfce88b36 100644
--- a/queues.md
+++ b/queues.md
@@ -13,6 +13,7 @@
     - [Preventing Job Overlaps](#preventing-job-overlaps)
     - [Throttling Exceptions](#throttling-exceptions)
     - [Skipping Jobs](#skipping-jobs)
+    - [Failing Jobs on Exceptions](#fail-job-on-exception)
 - [Dispatching Jobs](#dispatching-jobs)
     - [Delayed Dispatching](#delayed-dispatching)
     - [Synchronous Dispatching](#synchronous-dispatching)
@@ -814,6 +815,52 @@ public function middleware(): array
 }
 ```
 
+<a name="fail-job-on-exception"></a>
+### Failing Jobs
+The `FailOnException` job middleware allows you to short-circuit retries when specific exceptions are thrown. This allows retrying on transient exceptions such as external API errors, but failing the job permanently on persistent exceptions, such as a user's permissions being revoked.
+
+```php
+namespace App\Jobs;
+
+use App\Models\User;
+use Illuminate\Auth\Access\AuthorizationException;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Queue\Queueable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\Middleware\FailOnException;
+ 
+class SyncChatHistory implements ShouldQueue
+{
+    use InteractsWithQueue;
+
+    public $tries = 3;
+
+    public function __construct(
+        public User $user,
+    ) {}
+
+    public function handle(ChatService $chatService): void
+    {
+        $user->authorize('sync-chat-history');
+
+        // ...
+    }
+
+    /**
+     * Get the middleware the job should pass through.
+     */
+    public function middleware(): array
+    {
+        return [
+            new FailOnException([AuthorizationException::class])
+        ];
+    }
+}
+```
+
+> [!NOTE]
+> Your job must use the `Illuminate\Queue\InteractsWithQueue` trait.
+
 <a name="dispatching-jobs"></a>
 ## Dispatching Jobs
 

From 848b1a7e045d473e2cae5a7bf95b22b683b913de Mon Sep 17 00:00:00 2001
From: Luke Kuzmish <42181698+cosmastech@users.noreply.github.com>
Date: Tue, 17 Jun 2025 14:31:36 -0400
Subject: [PATCH 2/5] Update queues.md

---
 queues.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/queues.md b/queues.md
index 8adfce88b36..9f2e08d4910 100644
--- a/queues.md
+++ b/queues.md
@@ -816,7 +816,7 @@ public function middleware(): array
 ```
 
 <a name="fail-job-on-exception"></a>
-### Failing Jobs
+### Failing Jobs On Specific Exceptions
 The `FailOnException` job middleware allows you to short-circuit retries when specific exceptions are thrown. This allows retrying on transient exceptions such as external API errors, but failing the job permanently on persistent exceptions, such as a user's permissions being revoked.
 
 ```php
@@ -828,6 +828,7 @@ use Illuminate\Contracts\Queue\ShouldQueue;
 use Illuminate\Foundation\Queue\Queueable;
 use Illuminate\Queue\InteractsWithQueue;
 use Illuminate\Queue\Middleware\FailOnException;
+use Illuminate\Support\Facades\Http;
  
 class SyncChatHistory implements ShouldQueue
 {
@@ -839,10 +840,11 @@ class SyncChatHistory implements ShouldQueue
         public User $user,
     ) {}
 
-    public function handle(ChatService $chatService): void
+    public function handle(): void
     {
         $user->authorize('sync-chat-history');
 
+        $response = Http::throw()->get("https://chat.laravel.test/?user={$user->uuid}");
         // ...
     }
 

From c679d16a376df262db7e1259b37901bf7347099e Mon Sep 17 00:00:00 2001
From: Luke Kuzmish <42181698+cosmastech@users.noreply.github.com>
Date: Tue, 17 Jun 2025 14:32:32 -0400
Subject: [PATCH 3/5] Update queues.md

---
 queues.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/queues.md b/queues.md
index 9f2e08d4910..6a251198de1 100644
--- a/queues.md
+++ b/queues.md
@@ -840,14 +840,6 @@ class SyncChatHistory implements ShouldQueue
         public User $user,
     ) {}
 
-    public function handle(): void
-    {
-        $user->authorize('sync-chat-history');
-
-        $response = Http::throw()->get("https://chat.laravel.test/?user={$user->uuid}");
-        // ...
-    }
-
     /**
      * Get the middleware the job should pass through.
      */
@@ -857,6 +849,14 @@ class SyncChatHistory implements ShouldQueue
             new FailOnException([AuthorizationException::class])
         ];
     }
+
+    public function handle(): void
+    {
+        $user->authorize('sync-chat-history');
+
+        $response = Http::throw()->get("https://chat.laravel.test/?user={$user->uuid}");
+        // ...
+    }
 }
 ```
 

From 4490e4ecaa3591bbed77c5ef220bc7075cb9d083 Mon Sep 17 00:00:00 2001
From: Taylor Otwell <taylor@laravel.com>
Date: Tue, 17 Jun 2025 13:54:13 -0500
Subject: [PATCH 4/5] formatting

---
 queues.md | 105 +++++++++++++++++++++++++++++-------------------------
 1 file changed, 56 insertions(+), 49 deletions(-)

diff --git a/queues.md b/queues.md
index 6a251198de1..7c2a7147a2f 100644
--- a/queues.md
+++ b/queues.md
@@ -13,7 +13,6 @@
     - [Preventing Job Overlaps](#preventing-job-overlaps)
     - [Throttling Exceptions](#throttling-exceptions)
     - [Skipping Jobs](#skipping-jobs)
-    - [Failing Jobs on Exceptions](#fail-job-on-exception)
 - [Dispatching Jobs](#dispatching-jobs)
     - [Delayed Dispatching](#delayed-dispatching)
     - [Synchronous Dispatching](#synchronous-dispatching)
@@ -815,54 +814,6 @@ public function middleware(): array
 }
 ```
 
-<a name="fail-job-on-exception"></a>
-### Failing Jobs On Specific Exceptions
-The `FailOnException` job middleware allows you to short-circuit retries when specific exceptions are thrown. This allows retrying on transient exceptions such as external API errors, but failing the job permanently on persistent exceptions, such as a user's permissions being revoked.
-
-```php
-namespace App\Jobs;
-
-use App\Models\User;
-use Illuminate\Auth\Access\AuthorizationException;
-use Illuminate\Contracts\Queue\ShouldQueue;
-use Illuminate\Foundation\Queue\Queueable;
-use Illuminate\Queue\InteractsWithQueue;
-use Illuminate\Queue\Middleware\FailOnException;
-use Illuminate\Support\Facades\Http;
- 
-class SyncChatHistory implements ShouldQueue
-{
-    use InteractsWithQueue;
-
-    public $tries = 3;
-
-    public function __construct(
-        public User $user,
-    ) {}
-
-    /**
-     * Get the middleware the job should pass through.
-     */
-    public function middleware(): array
-    {
-        return [
-            new FailOnException([AuthorizationException::class])
-        ];
-    }
-
-    public function handle(): void
-    {
-        $user->authorize('sync-chat-history');
-
-        $response = Http::throw()->get("https://chat.laravel.test/?user={$user->uuid}");
-        // ...
-    }
-}
-```
-
-> [!NOTE]
-> Your job must use the `Illuminate\Queue\InteractsWithQueue` trait.
-
 <a name="dispatching-jobs"></a>
 ## Dispatching Jobs
 
@@ -1477,6 +1428,62 @@ $this->fail('Something went wrong.');
 > [!NOTE]
 > For more information on failed jobs, check out the [documentation on dealing with job failures](#dealing-with-failed-jobs).
 
+<a name="fail-jobs-on-exceptions"></a>
+#### Failing Jobs on Specific Exceptions
+
+The `FailOnException` [job middleware](#job-middleware) allows you to short-circuit retries when specific exceptions are thrown. This allows retrying on transient exceptions such as external API errors, but failing the job permanently on persistent exceptions, such as a user's permissions being revoked:
+
+```php
+namespace App\Jobs;
+
+use App\Models\User;
+use Illuminate\Auth\Access\AuthorizationException;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Queue\Queueable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\Middleware\FailOnException;
+use Illuminate\Support\Facades\Http;
+
+class SyncChatHistory implements ShouldQueue
+{
+    use InteractsWithQueue;
+
+    public $tries = 3;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(
+        public User $user,
+    ) {}
+
+    /**
+     * Execute the job.
+     */
+    public function handle(): void
+    {
+        $user->authorize('sync-chat-history');
+
+        $response = Http::throw()->get(
+            "https://chat.laravel.test/?user={$user->uuid}
+        ");
+
+
+        // ...
+    }
+
+    /**
+     * Get the middleware the job should pass through.
+     */
+    public function middleware(): array
+    {
+        return [
+            new FailOnException([AuthorizationException::class])
+        ];
+    }
+}
+```
+
 <a name="job-batching"></a>
 ## Job Batching
 

From fe75300e9ed4814c11c89f41f5752ecaed2732a8 Mon Sep 17 00:00:00 2001
From: Taylor Otwell <taylor@laravel.com>
Date: Tue, 17 Jun 2025 13:54:57 -0500
Subject: [PATCH 5/5] wip

---
 queues.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/queues.md b/queues.md
index 7c2a7147a2f..affb97025e0 100644
--- a/queues.md
+++ b/queues.md
@@ -1434,6 +1434,8 @@ $this->fail('Something went wrong.');
 The `FailOnException` [job middleware](#job-middleware) allows you to short-circuit retries when specific exceptions are thrown. This allows retrying on transient exceptions such as external API errors, but failing the job permanently on persistent exceptions, such as a user's permissions being revoked:
 
 ```php
+<?php
+
 namespace App\Jobs;
 
 use App\Models\User;