README

🚦 Laravel Notification Channel Throttling

Throttle your Laravel notifications on a per-channel basis

Introduction

When sending notifications through multiple channels (say email and SMS), you may want to throttle the number of notifications sent through a specific channel. For example, you could limit the number of SMS notifications sent to a user to 1 per day, and limit emails to 5 per day. This package allows you to configure this easily directly in your notification classes.

Installation

You can install the package via composer:

composer require syropian/laravel-notification-channel-throttling

Compatibility

This package supports Laravel 10, 11, 12, and 13.

Laravel 13 requires PHP 8.3. The package still supports PHP 8.2 for Laravel 10, 11, and 12.

Usage

1. Ensure the notification you want to throttle implements Syropian\LaravelNotificationChannelThrottling\Contracts\ThrottlesChannels.
2. Implement the throttleChannels method. This method should return an array of channels to throttle, and the configuration for each channel. To omit a channel from throttling either omit the channel from the array, or set the value to false.

use Illuminate\Notifications\Notification;
use Syropian\LaravelNotificationChannelThrottling\Contracts\ThrottlesChannels;

class ExampleNotification extends Notification implements ThrottlesChannels {
    // ...

    public function throttleChannels(object $notifiable, array $channels): array
    {
        /**
         * Throttle the mail channel, so that only one
         * email notification is sent every 15 minutes
         */
        return [
            'mail' => [
                'maxAttempts' => 1,
                'decaySeconds' => 900,
            ],
            'database' => false,
        ];
    }
}

Scoping the rate limiter

By default, the rate limiter instance used to throttle is automatically scoped to the notification and channel. If you would like to further scope the rate limiter, you may pass a key to the channel configuration.

public function __construct(public Post $post) {}

public function throttleChannels(object $notifiable, array $channels): array
{
    return [
        'mail' => [
            'key' => $notifiable->id . ':' . $this->post->id,
            'maxAttempts' => 1,
            'decaySeconds' => 900,
        ],
        'database' => false,
    ];
}

In this example we're rate limiting the mail channel, and we're scoping it to a specific combination of a user and a post.

Testing

composer test

Credits

• Collin Henderson
• All Contributors

License

The MIT License (MIT). Please see License File for more information.