Download the PHP package codinglabsau/laravel-notification-subscriptions without Composer

Laravel Notification Subscriptions

A Laravel package for managing user notification preferences across multiple channels. Let your users control how they receive notifications (email, in-app, push, Slack) while you maintain sensible defaults and rate limiting.

Features

• Channel-based subscriptions - Users can enable/disable notifications per channel
• Custom channels - Define your own channel enum with any channels you need (mail, database, Slack, Pusher, OneSignal, etc.)
• Per-notification control - Configure which channels each notification type supports
• Smart defaults - New users get sensible defaults; preferences are only stored when changed
• Rate limiting - Prevent notification spam with configurable per-channel rate limits
• Mandatory channels - Per-notification channels that users can't opt out of
• Simple API - $user->getNotificationPreferences() and $user->updateNotificationPreferences() for settings UIs

Installation

1. Install via Composer

2. Publish and run migrations

3. Publish configuration (optional)

4. Create your channel enum

Create an enum that implements SubscribableChannel to define your notification channels:

5. Add trait to your User model

6. Publish and configure the service provider

Then register your subscribable notifications in app/Providers/NotificationSubscriptionsServiceProvider.php:

Don't forget to add this service provider to your bootstrap/providers.php:

Basic Usage

Creating a Subscribable Notification

Transform any Laravel notification into a subscribable notification by implementing the SubscribableNotification interface and using the DispatchesNotifications trait:

Dispatching Notifications

Use the static sendToSubscribers() method instead of Laravel's standard notification sending:

Transactional vs Subscribable Notifications

How It Works

When a notification is dispatched:

1. Subscriber lookup - The subscribers() method determines who should receive the notification
2. Channel filtering - For each subscriber, the package checks their preferences:
   • If they have a stored preference for this notification type, only enabled channels are used
   • If no preference exists, channels with defaultOn() === true are used
3. Rate limiting - If a channel has rate limiting enabled and the notification has a subject, duplicate notifications are throttled
4. Delivery - The notification is sent only to the appropriate channels

Channel Enum Reference

Your channel enum must implement SubscribableChannel with these methods:

Example: Advanced Channel Configuration

Rate Limiting

Rate limiting prevents notification spam when the same notification could be triggered multiple times in quick succession.

How Rate Limiting Works

Rate limits are applied per combination of:

• Notification type (e.g., order_shipped)
• Channel (e.g., mail)
• Subject (the model that triggered the notification)
• Recipient (the user receiving the notification)

Subject Method

For rate limiting to work, your notification must return a subject:

If subject() returns null, rate limiting is skipped for that notification.

Mandatory Channels

Some notifications must always be sent via certain channels regardless of user preferences. For example, a support ticket reply might always need an email notification, even if the user has opted out of email for other notifications.

Defining Mandatory Channels

Override mandatoryChannels() in your notification class to specify channels that cannot be unsubscribed from:

By default, mandatoryChannels() returns an empty array, meaning all channels are optional.

How Mandatory Channels Work

Mandatory channels are enforced at three levels:

1. shouldSend() defense-in-depth — When dispatching a notification, mandatory channels always return true in shouldSend(), even if the user's subscription record excludes them. This ensures delivery even with stale subscription data.

2. Validation re-injection — The ValidatesNotificationPreferences trait automatically re-injects mandatory channels into form requests during prepareForValidation(), so they can never be removed by user input.

3. NotificationPreferences DTO — The getNotificationPreferences() method populates a mandatory property on the DTO, mapping each notification type to its mandatory channel values. This allows your UI to render mandatory channels as disabled/locked checkboxes.

Using Mandatory Data in the UI

The NotificationPreferences DTO includes a mandatory property:

Use this in your frontend to disable checkboxes for mandatory channels:

Building a Settings UI

The package provides a simple API for building notification preference UIs. The HasNotificationSubscriptions trait adds two methods to your User model:

• getNotificationPreferences() - Returns a DTO with types and values for the UI
• updateNotificationPreferences(array $preferences) - Updates preferences in the database

Controller Setup

The ValidatesNotificationPreferences trait:

• Generates validation rules for each registered notification type
• Automatically re-injects mandatory channels (users can't opt out of them)

The NotificationPreferences DTO

The getNotificationPreferences() method returns a NotificationPreferences object with three properties:

Example Blade Template

Inertia/Vue Example

Advanced Usage

Custom Notification Labels

Add metadata methods to your notifications for richer UIs:

Before Send Hook

Execute code before any notification is sent:

Custom Subscription Model

Extend the base model if you need additional functionality:

Database Schema

The package creates a notification_subscriptions table:

A unique constraint ensures one subscription record per user/type combination.

Testing

Credits

• Coding Labs
• All Contributors

License

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