document after commit interfaces

Author: taylorotwell

broadcasting.md

@@ -507,20 +507,19 @@ Sometimes you want to broadcast your event only if a given condition is true. Yo
 
 When broadcast events are dispatched within database transactions, they may be processed by the queue before the database transaction has committed. When this happens, any updates you have made to models or database records during the database transaction may not yet be reflected in the database. In addition, any models or database records created within the transaction may not exist in the database. If your event depends on these models, unexpected errors can occur when the job that broadcasts the event is processed.
 
-If your queue connection's `after_commit` configuration option is set to `false`, you may still indicate that a particular broadcast event should be dispatched after all open database transactions have been committed by defining an `$afterCommit` property on the event class:
+If your queue connection's `after_commit` configuration option is set to `false`, you may still indicate that a particular broadcast event should be dispatched after all open database transactions have been committed by implementing the `ShouldDispatchAfterCommit` interface on the event class:
 
     <?php
 
     namespace App\Events;
 
     use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+    use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;
     use Illuminate\Queue\SerializesModels;
 
-    class ServerCreated implements ShouldBroadcast
+    class ServerCreated implements ShouldBroadcast, ShouldDispatchAfterCommit
     {
         use SerializesModels;
-
-        public $afterCommit = true;
     }
 
 > **Note**  

eloquent.md

@@ -1549,23 +1549,17 @@ Alternatively, you may list your observers within an `$observers` property of yo
 <a name="observers-and-database-transactions"></a>
 #### Observers & Database Transactions
 
-When models are being created within a database transaction, you may want to instruct an observer to only execute its event handlers after the database transaction is committed. You may accomplish this by defining an `$afterCommit` property on the observer. If a database transaction is not in progress, the event handlers will execute immediately:
+When models are being created within a database transaction, you may want to instruct an observer to only execute its event handlers after the database transaction is committed. You may accomplish this by implementing the `ShouldHandleEventsAfterCommit` interface on your observer. If a database transaction is not in progress, the event handlers will execute immediately:
 
     <?php
 
     namespace App\Observers;
 
     use App\Models\User;
+    use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;
 
-    class UserObserver
+    class UserObserver implements ShouldHandleEventsAfterCommit
     {
-        /**
-         * Handle events after all transactions are committed.
-         *
-         * @var bool
-         */
-        public $afterCommit = true;
-
         /**
          * Handle the User "created" event.
          */

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)
+    - [Dispatching Events After Database Transactions](#dispatching-events-after-database-transactions)
 - [Event Subscribers](#event-subscribers)
     - [Writing Event Subscribers](#writing-event-subscribers)
     - [Registering Event Subscribers](#registering-event-subscribers)
@@ -398,20 +399,19 @@ If you need to manually access the listener's underlying queue job's `delete` an
 
 When queued listeners are dispatched within database transactions, they may be processed by the queue before the database transaction has committed. When this happens, any updates you have made to models or database records during the database transaction may not yet be reflected in the database. In addition, any models or database records created within the transaction may not exist in the database. If your listener depends on these models, unexpected errors can occur when the job that dispatches the queued listener is processed.
 
-If your queue connection's `after_commit` configuration option is set to `false`, you may still indicate that a particular queued listener should be dispatched after all open database transactions have been committed by defining an `$afterCommit` property on the listener class:
+If your queue connection's `after_commit` configuration option is set to `false`, you may still indicate that a particular queued listener should be dispatched after all open database transactions have been committed by implementing the `ShouldHandleEventsAfterCommit` interface on the listener class:
 
     <?php
 
     namespace App\Listeners;
 
+    use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;
     use Illuminate\Contracts\Queue\ShouldQueue;
     use Illuminate\Queue\InteractsWithQueue;
 
-    class SendShipmentNotification implements ShouldQueue
+    class SendShipmentNotification implements ShouldQueue, ShouldHandleEventsAfterCommit
     {
         use InteractsWithQueue;
-
-        public $afterCommit = true;
     }
 
 > **Note**  
@@ -532,6 +532,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="dispatching-events-after-database-transactions"></a>
+### Dispatching Events After Database Transactions
+
+Sometimes, you may want to instruct Laravel to only dispatch an event after the active database transaction has committed. To do so, you may implement the `ShouldDispatchAfterCommit` interface on the event class.
+
+This interface instructs Laravel to not dispatch the event until the current database transaction is committed. If the transaction fails, the event will be discarded. If no database transaction is in progress when the event is dispatched, the event will be dispatched immediately:
+
+    <?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,
+        ) {}
+    }
+
 <a name="event-subscribers"></a>
 ## Event Subscribers