Laravel Best Practices

rules/events-notifications.blade.php

@php
/** @var \Laravel\Boost\Install\GuidelineAssist $assist */
@endphp
# Events and notifications best practices

## Rely on event discovery

Laravel discovers listeners in the configured listener directories by inspecting type-hinted event arguments on `handle()` or `__invoke()` methods. Register listeners manually only when discovery is disabled, the listener is outside those directories, or explicit registration is clearer.

## Cache event discovery during production deployment

Cache discovered listeners during production deployment with `{{ $assist->artisanCommand('optimize') }}` or `{{ $assist->artisanCommand('event:cache') }}`. Rebuild the cache whenever listener definitions change.

## Use `ShouldDispatchAfterCommit` inside transactions

When you dispatch an event inside a database transaction, `ShouldDispatchAfterCommit` delays dispatch until all open database transactions commit. If a transaction rolls back, Laravel discards the event. The delay affects synchronous and queued listeners. It is not limited to queue timing.

```php
class OrderShipped implements ShouldDispatchAfterCommit {}
```

## Queue slow notifications

Queue notifications that call external services, such as email, text messaging, or Slack, when they do not need to complete before the response. Keep a notification synchronous when immediate completion or failure feedback is part of the operation.

```php
class InvoicePaid extends Notification implements ShouldQueue
{
    use Queueable;
}
```

## Dispatch queued notifications after commit

A queued notification sent inside a database transaction can run before the transaction commits. Call `afterCommit()` on the queued notification, or enable the queue connection's `after_commit` option, when its delivery depends on committed data. Neither option has a scheduling effect on a synchronous notification.

```php
$user->notify((new InvoicePaid($invoice))->afterCommit());
```

## Route notification channels to dedicated queues

Different notification channels can have different latency and priority requirements. Implement `viaQueues()` when channels should use separate queues.

## Use on-demand notifications for non-user recipients

Avoid creating dummy models to send notifications to arbitrary addresses.

```php
Notification::route('mail', '[email protected]')->notify(new SystemAlert());
```

## Implement `HasLocalePreference` on notifiable models

Implement `HasLocalePreference::preferredLocale()` on a notifiable model when notifications and mailables should use the recipient's locale. Laravel also preserves that locale for queued delivery. An explicit `locale()` call can still override the preference for an individual notification.