From bb33bb9c1b00f5ef33308c1e27fed945f4f52868 Mon Sep 17 00:00:00 2001 From: Steve Bauman Date: Mon, 21 Jul 2025 16:50:27 -0400 Subject: [PATCH 1/5] Add max exceptions docs to queued listener --- events.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/events.md b/events.md index 7ad8548f8bd..05a4adfb7e8 100644 --- a/events.md +++ b/events.md @@ -577,6 +577,50 @@ public function backoff(): array } ``` + +#### Specifying Queued Listener Max Exceptions + +Sometimes you may wish to specify that a queued listener may be attempted many times, but should fail if the retries are triggered by a given number of unhandled exceptions (as opposed to being released by the `release` method directly). To accomplish this, you may define a `maxExceptions` property on your listener class: + +```php + ## Dispatching Events From 612e619b181b7812051265d03ec59e4dd4e20ea6 Mon Sep 17 00:00:00 2001 From: Steve Bauman Date: Mon, 21 Jul 2025 16:57:07 -0400 Subject: [PATCH 2/5] Add docs for remaining properties --- events.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) diff --git a/events.md b/events.md index 05a4adfb7e8..607568b72f6 100644 --- a/events.md +++ b/events.md @@ -452,6 +452,29 @@ class SendShipmentNotification implements ShouldQueueAfterCommit } ``` +Alternatively, instead of implementing the `ShouldQueueAfterCommit` interface, you may define an `$afterCommit` property on your listener class: + +```php + [!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). @@ -621,6 +644,110 @@ class SendShipmentNotification implements ShouldQueue In this example, the listener will be retried up to 25 times. However, the listener will fail if three unhandled exceptions are thrown by the listener. + +#### Specifying Queued Listener Timeout + +Often, you know roughly how long you expect your queued listeners to take. For this reason, Laravel allows you to specify a "timeout" value. If a listener is processing for longer than the number of seconds specified by the timeout value, the worker processing the listener will exit with an error. You may define the maximum number of seconds a listener should be allowed to run by defining a `$timeout` property on your listener class: + +```php + +#### Failing Queued Listeners on Timeout + +If you would like to indicate that a listener should be marked as failed on timeout, you may define the `$failOnTimeout` property on the listener class: + +```php + +#### Encrypted Queued Listeners + +Laravel allows you to ensure the privacy and integrity of a queued listener's data via [encryption](/docs/{{version}}/encryption). To get started, simply add the `ShouldBeEncrypted` interface to the listener class. Once this interface has been added to the class, Laravel will automatically encrypt your listener before pushing it onto a queue: + +```php + +#### Queued Listener Middleware + +Queued listeners can also utilize [job middleware](/docs/{{version}}/queues#job-middleware). Job middleware allow you to wrap custom logic around the execution of queued listeners, reducing boilerplate in the listeners themselves. After creating job middleware, they may be attached to a listener by returning them from the listener's `middleware` method: + +```php + + */ + public function middleware(): array + { + return [new RateLimited]; + } + + /** + * Handle the event. + */ + public function handle(OrderShipped $event): void + { + // Process the event... + } +} +``` + ## Dispatching Events From 122578a0731d2a730131b423eb49ac0aa804fc7f Mon Sep 17 00:00:00 2001 From: Steve Bauman Date: Mon, 21 Jul 2025 17:03:34 -0400 Subject: [PATCH 3/5] Add parameters to inform developers of their availability --- events.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/events.md b/events.md index 607568b72f6..4e4ebab6630 100644 --- a/events.md +++ b/events.md @@ -580,7 +580,7 @@ If you require more complex logic for determining the listeners's backoff time, /** * Calculate the number of seconds to wait before retrying the queued listener. */ -public function backoff(): int +public function backoff(OrderShipped $event): int { return 3; } @@ -594,7 +594,7 @@ You may easily configure "exponential" backoffs by returning an array of backoff * * @return list */ -public function backoff(): array +public function backoff(OrderShipped $event): array { return [1, 5, 10]; } @@ -733,7 +733,7 @@ class SendShipmentNotification implements ShouldQueue * * @return array */ - public function middleware(): array + public function middleware(OrderShipped $event): array { return [new RateLimited]; } From ada5a93b3f8ca0b9611c853da3b3dba093728191 Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Tue, 22 Jul 2025 10:34:24 -0500 Subject: [PATCH 4/5] Update events.md --- events.md | 23 ----------------------- 1 file changed, 23 deletions(-) diff --git a/events.md b/events.md index 4e4ebab6630..ecdb85ad6b1 100644 --- a/events.md +++ b/events.md @@ -452,29 +452,6 @@ class SendShipmentNotification implements ShouldQueueAfterCommit } ``` -Alternatively, instead of implementing the `ShouldQueueAfterCommit` interface, you may define an `$afterCommit` property on your listener class: - -```php - [!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). From 132cbe36122205985389d81819c03bed6408fe8f Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Tue, 22 Jul 2025 10:38:31 -0500 Subject: [PATCH 5/5] formatting --- events.md | 117 +++++++++++++++++++++++++++--------------------------- 1 file changed, 58 insertions(+), 59 deletions(-) diff --git a/events.md b/events.md index ecdb85ad6b1..9671f427bce 100644 --- a/events.md +++ b/events.md @@ -11,6 +11,8 @@ - [Queued Event Listeners](#queued-event-listeners) - [Manually Interacting With the Queue](#manually-interacting-with-the-queue) - [Queued Event Listeners and Database Transactions](#queued-event-listeners-and-database-transactions) + - [Queued Listener Middleware](#queued-listener-middleware) + - [Encrypted Queued Listeners](#encrypted-queued-listeners) - [Handling Failed Jobs](#handling-failed-jobs) - [Dispatching Events](#dispatching-events) - [Dispatching Events After Database Transactions](#dispatching-events-after-database-transactions) @@ -455,6 +457,62 @@ class SendShipmentNotification implements ShouldQueueAfterCommit > [!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). + +### Queued Listener Middleware + +Queued listeners can also utilize [job middleware](/docs/{{version}}/queues#job-middleware). Job middleware allow you to wrap custom logic around the execution of queued listeners, reducing boilerplate in the listeners themselves. After creating job middleware, they may be attached to a listener by returning them from the listener's `middleware` method: + +```php + + */ + public function middleware(OrderShipped $event): array + { + return [new RateLimited]; + } +} +``` + + +#### Encrypted Queued Listeners + +Laravel allows you to ensure the privacy and integrity of a queued listener's data via [encryption](/docs/{{version}}/encryption). To get started, simply add the `ShouldBeEncrypted` interface to the listener class. Once this interface has been added to the class, Laravel will automatically encrypt your listener before pushing it onto a queue: + +```php + ### Handling Failed Jobs @@ -645,9 +703,6 @@ class SendShipmentNotification implements ShouldQueue } ``` - -#### Failing Queued Listeners on Timeout - If you would like to indicate that a listener should be marked as failed on timeout, you may define the `$failOnTimeout` property on the listener class: ```php @@ -669,62 +724,6 @@ class SendShipmentNotification implements ShouldQueue } ``` - -#### Encrypted Queued Listeners - -Laravel allows you to ensure the privacy and integrity of a queued listener's data via [encryption](/docs/{{version}}/encryption). To get started, simply add the `ShouldBeEncrypted` interface to the listener class. Once this interface has been added to the class, Laravel will automatically encrypt your listener before pushing it onto a queue: - -```php - -#### Queued Listener Middleware - -Queued listeners can also utilize [job middleware](/docs/{{version}}/queues#job-middleware). Job middleware allow you to wrap custom logic around the execution of queued listeners, reducing boilerplate in the listeners themselves. After creating job middleware, they may be attached to a listener by returning them from the listener's `middleware` method: - -```php - - */ - public function middleware(OrderShipped $event): array - { - return [new RateLimited]; - } - - /** - * Handle the event. - */ - public function handle(OrderShipped $event): void - { - // Process the event... - } -} -``` - ## Dispatching Events