Download the PHP package offload-project/laravel-notification-preferences without Composer

Laravel Notification Preferences

A Laravel package for managing user notification preferences with support for multiple channels, notification groups, and automatic channel filtering — perfect for building notification settings UIs.

Features

• Automatic Filtering — All notifications respect user preferences without code changes
• Multiple Channels — Support for mail, database, broadcast, SMS, or custom channels
• Notification Grouping — Organize notifications into logical groups (system, marketing, etc.)
• Forced Channels — Critical notifications that users cannot disable
• Permission Gating — Hook into Laravel's Gate to hide and block notifications users aren't authorized to receive
• Bulk Operations — Disable all emails, mute a group, or toggle notification types
• Structured Output — UI-ready table structure for building preference pages
• Opt-in/Opt-out Defaults — Configure default behavior at global, group, or notification level
• Event Dispatching — Listen for preference changes for audit logging or sync
• Email Unsubscribe Links — Signed URLs for one-click unsubscribe with List-Unsubscribe header support
• Input Validation — Prevents setting preferences for unregistered notifications/channels

Requirements

• PHP 8.3+
• Laravel 11/12/13

Installation

Publish the config and migrations:

Quick Start

1. Add the trait to your User model:

2. Register your notifications in config/notification-preferences.php:

3. Send notifications normally — preferences are applied automatically:

Managing Preferences

Bulk Operations

Convenient methods for "disable all emails" or "mute marketing" features:

All bulk methods return the count of updated preferences and automatically skip forced channels.

Explicit Control with Trait

For granular control, use the ChecksNotificationPreferences trait in your notification:

Forced Channels

Prevent users from disabling critical notifications:

Permission Gating

Tie notifications to a Gate ability so users only see — and only receive — notifications they're authorized for. Works with native policies, Spatie Permission, Bouncer, or any package that registers with Laravel's Gate.

Option 1: Implement the interface (recommended for notifications you own):

Option 2: Declare the ability in config (for notifications from other packages):

When a user fails the Gate check:

• Dispatch is blocked across all channels — authorization overrides forced channels and self-filtering traits.
• The notification is hidden from getPreferencesTable() so the UI doesn't expose toggles for things they can't access.
• A NotificationAuthorizationDenied event is dispatched per blocked channel for observability.

The notification instance is passed to your Gate closure at dispatch time, so you can authorize against the payload:

Per-Channel Defaults

Set specific channels enabled by default:

Events

The package dispatches events when preferences change:

NotificationAuthorizationDenied is dispatched whenever a notification is blocked by a failing Gate check (see Permission Gating):

Using the Facade

For quick access without dependency injection:

Using the Interface

For dependency injection and testing, use the interface:

Table Structure Output

The getNotificationPreferencesTable() method returns UI-ready data:

Inertia.js Integration

Share preferences via middleware:

Cache Management

Preferences are cached for performance (default: 24 hours). Configure the TTL in your config:

Clear caches when needed:

Exception Handling

The package validates all inputs and throws specific exceptions with helpful messages:

Email Unsubscribe Links

The package can generate signed URLs that let users unsubscribe directly from emails — no login required. It also supports List-Unsubscribe headers for native unsubscribe buttons in Gmail, Apple Mail, and other clients (RFC 8058).

Adding Unsubscribe Links to Notifications

Use the HasUnsubscribeUrl trait on your notification class:

withUnsubscribeHeaders() adds List-Unsubscribe and List-Unsubscribe-Post headers so email clients can show native unsubscribe buttons. The getUnsubscribeUrl() method generates a signed URL you can place anywhere in the email body.

Generating URLs Directly

You can also generate URLs from the user model or facade:

How It Works

When a user clicks the unsubscribe link, the package:

1. Validates the signed URL (tamper-proof, no auth required)
2. Disables the notification type for that channel
3. Returns a JSON response, or redirects to your configured URL

The POST method is also supported for RFC 8058 one-click unsubscribe from email clients.

Configuration

Redirect Example

When redirect_url is set, users are redirected after unsubscribing:

This lets you handle the confirmation page in your own frontend (Blade, Inertia, Livewire, etc.).

Uninstalling

Configuration Reference

Global Options

Channels

Groups

Notifications

Unsubscribe

Testing

License

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