[10.x] Add AfterCommit interfaces and ShouldDispatchAfterCommit docs

events.md

@@ -12,6 +12,7 @@
     - [Queued Event Listeners & Database Transactions](#queued-event-listeners-and-database-transactions)
     - [Handling Failed Jobs](#handling-failed-jobs)
 - [Dispatching Events](#dispatching-events)
+    - [Interacting with Database Transactions](#interacting-with-database-transactions)
 - [Event Subscribers](#event-subscribers)
     - [Writing Event Subscribers](#writing-event-subscribers)
     - [Registering Event Subscribers](#registering-event-subscribers)
@@ -414,6 +415,22 @@ If your queue connection's `after_commit` configuration option is set to `false`
         public $afterCommit = true;
     }
 
+Alternatively, you might also implement the `ShouldHandleEventsAfterCommit` interface:
+
+    <?php
+
+    namespace App\Listeners;
+
+    use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;
+    use Illuminate\Contracts\Queue\ShouldQueue;
+    use Illuminate\Queue\InteractsWithQueue;
+
+    class SendShipmentNotification implements ShouldQueue, ShouldHandleEventsAfterCommit
+    {
+        use InteractsWithQueue;
+    }
+
+
 > **Note**  
 > To learn more about working around these issues, please review the documentation regarding [queued jobs and database transactions](/docs/{{version}}/queues#jobs-and-database-transactions).
 
@@ -532,6 +549,35 @@ To dispatch an event, you may call the static `dispatch` method on the event. Th
 > **Note**  
 > When testing, it can be helpful to assert that certain events were dispatched without actually triggering their listeners. Laravel's [built-in testing helpers](#testing) make it a cinch.
 
+<a name="interacting-with-database-transactions"></a>
+### Interacting with Database Transactions
+
+Whenever you're dealing with database transactions, you might want the events to only be dispatched once the transaction is committed. To do so, you can implement the `ShouldDispatchAfterCommit` interface on the Event class:
+
+    <?php
+
+    namespace App\Events;
+
+    use App\Models\Order;
+    use Illuminate\Broadcasting\InteractsWithSockets;
+    use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;
+    use Illuminate\Foundation\Events\Dispatchable;
+    use Illuminate\Queue\SerializesModels;
+
+    class OrderShipped implements ShouldDispatchAfterCommit
+    {
+        use Dispatchable, InteractsWithSockets, SerializesModels;
+
+        /**
+         * Create a new event instance.
+         */
+        public function __construct(
+            public Order $order,
+        ) {}
+    }
+
+>Each database transaction's events are isolated. If a transaction fails, its events will be discarded and it will not affect the parent transaction.
+
 <a name="event-subscribers"></a>
 ## Event Subscribers
 

queues.md

@@ -816,6 +816,43 @@ Likewise, if the `after_commit` configuration option is set to `true`, you may i
 
     ProcessPodcast::dispatch($podcast)->beforeCommit();
 
+<a name="specifying-commit-dispatch-behavior-on-the-job-class"></a>
+#### Specifying Commit Dispatch Behavior On The Job Class
+
+Alternatively, if you want to specify the commit dispatch behavior inside the job class, you can do so by implementing the `ShouldQueueAfterCommit` interface instead of `ShouldQueue`:
+
+    <?php
+
+    namespace App\Jobs;
+
+    use App\Models\Podcast;
+    use App\Services\AudioProcessor;
+    use Illuminate\Bus\Queueable;
+    use Illuminate\Contracts\Queue\ShouldQueueAfterCommit;
+    use Illuminate\Foundation\Bus\Dispatchable;
+    use Illuminate\Queue\InteractsWithQueue;
+    use Illuminate\Queue\SerializesModels;
+
+    class ProcessPodcast implements ShouldQueueAfterCommit
+    {
+        use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+        /**
+         * Create a new job instance.
+         */
+        public function __construct(
+            public Podcast $podcast,
+        ) {}
+
+        /**
+         * Execute the job.
+         */
+        public function handle(AudioProcessor $processor): void
+        {
+            // Process uploaded podcast...
+        }
+    }
+
 <a name="job-chaining"></a>
 ### Job Chaining