├── .gitignore ├── LICENSE ├── README.md ├── composer.json ├── config └── notification-subscriptions.php ├── database └── migrations │ └── 2020_05_20_000001_create_notification_subscriptions_table.php └── src ├── Events └── NotificationSuppressed.php ├── Listeners └── NotificationSendingListener.php ├── Models └── NotificationSubscription.php ├── NotificationSubscriptionsServiceProvider.php ├── Providers └── EventServiceProvider.php └── Traits └── HasNotificationSubscriptions.php /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_STORE 2 | vendor 3 | .phpunit.result.cache 4 | composer.lock -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Liran Cohen 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Laravel Notification Subscriptions 2 | 3 | Laravel Notification Subscriptions is a package that hooks directly into Laravel's existing [notification system](https://laravel.com/docs/master/notifications) and adds functionality to manage user subscriptions to your app's notifications and suppress them automatically when they shouldn't be sent. You can subscribe and unsubscribe users to specific notification channels, create opt-in notifications, and scope your subscriptions by another model. 4 | 5 | [![Latest Stable Version](https://poser.pugx.org/liran-co/laravel-notification-subscriptions/v/stable)](https://packagist.org/packages/liran-co/laravel-notification-subscriptions) [![Total Downloads](https://poser.pugx.org/liran-co/laravel-notification-subscriptions/downloads)](https://packagist.org/packages/liran-co/laravel-notification-subscriptions) [![License](https://poser.pugx.org/liran-co/laravel-notification-subscriptions/license)](https://packagist.org/packages/liran-co/laravel-notification-subscriptions) 6 | 7 | ## Installation 8 | 9 | To get started, install the `liran-co/laravel-notification-subscriptions` package: 10 | 11 | ```bash 12 | composer require liran-co/laravel-notification-subscriptions 13 | ``` 14 | 15 | Run the migration to create the `notification_subscriptions` table: 16 | ```bash 17 | php artisan migrate 18 | ``` 19 | 20 | Optionally publish the configuration file by running and selecting the appropriate provider option: 21 | ```bash 22 | php artisan vendor:publish 23 | ``` 24 | 25 | ## Basic usage 26 | 27 | This package uses a [Listener](https://laravel.com/docs/master/events) to listen for any notifications that get sent in your application. When a notification gets triggered, the package checks to see if the notification should actually be sent according to the user's subscriptions. If not, the notification is suppressed. 28 | 29 | ### Getting started 30 | 31 | This package assumes you've already setup Laravel's notification system. If you haven't [read the docs](https://laravel.com/docs/master/notifications) to get started. 32 | 33 | Add the `HasNotificationSubscriptions ` trait to your `User` model: 34 | 35 | ```php 36 | use Illuminate\Database\Eloquent\Model; 37 | use LiranCo\NotificationSubscriptions\Traits\HasNotificationSubscriptions; 38 | 39 | class User extends Model 40 | { 41 | use HasNotificationSubscriptions; 42 | 43 | // ... 44 | } 45 | ``` 46 | 47 | ### Unsubscribing 48 | 49 | To unsubscribe a user from a specific `Notification`, pass the class name of that notification to the `unsubscribe` function. 50 | 51 | ```php 52 | use App\Notifications\InvoicePaid; 53 | 54 | $user->unsubscribe(InvoicePaid::class); //You can also pass a string, but this is the preferred method. 55 | ``` 56 | 57 | The above will unsubscribe the user from all channels. You can unsubscribe a user from a specific channel by passing the channel name as the second parameter: 58 | 59 | ```php 60 | use App\Notifications\InvoicePaid; 61 | 62 | $user->unsubscribe(InvoicePaid::class, 'mail'); 63 | ``` 64 | 65 | Now, whenever an `InvoicePaid` notification is sent, the package will automatically detect that the user has unsubscribed and suppress the notification. For example: 66 | 67 | ```php 68 | use App\Notifications\InvoicePaid; 69 | 70 | $user->notify(new InvoicePaid($invoice)); //This won't get sent. 71 | ``` 72 | 73 | ### Opt-in notifications 74 | 75 | By default, all notifications will be sent if no subscribe/unsubscribe record is found. This means you don't need to explicitly **subscribe** a user to a notification, you only need to **unsubscribe** them. 76 | 77 | In some cases, however, you'd like to create opt-in notifications. To do so, modify your notification class and add a function called `getOptInSubscriptions`: 78 | 79 | ```php 80 | subscribe(InvoicePaid::class); 110 | ``` 111 | 112 | Similarly, you can apply a channel: 113 | 114 | ```php 115 | use App\Notifications\InvoicePaid; 116 | 117 | $user->subscribe(InvoicePaid::class, 'mail'); 118 | ``` 119 | 120 | ### Resetting subscriptions 121 | 122 | This package makes no assumptions about how your application manages notifications and subscriptions. For example, if you unsubscribe a user from a particular notification channel, and later subscribe them to all channels, the previous record won't be deleted. To reset the notifications on a user: 123 | 124 | ```php 125 | use App\Notifications\InvoicePaid; 126 | 127 | $user->resetSubscriptions(InvoicePaid::class); 128 | ``` 129 | 130 | You can chain the `resetSubscriptions`: 131 | 132 | ```php 133 | use App\Notifications\InvoicePaid; 134 | 135 | $user->resetSubscriptions(InvoicePaid::class)->subscribe(InvoicePaid::class); 136 | ``` 137 | 138 | ### Retrieving subscriptions 139 | 140 | You can get a user's subscriptions by using the `notificationSubscriptions()` relation: 141 | 142 | ```php 143 | $user->notificationSubscriptions(); 144 | ``` 145 | 146 | ## Model scoping 147 | 148 | In some applications, you need to unsubscribe users from notifications related to a certain model. For example, if a user is a part of multiple organizations, they may only want to unsubscribe from a single organization. You can accomplish this by applying a model scope to your notifications: 149 | 150 | ```php 151 | use App\Models\Organization; 152 | use App\Notifications\InvoicePaid; 153 | 154 | //... 155 | 156 | $organization = Organization::find(1); 157 | 158 | $user->unsubscribe(InvoicePaid::class, '*', $organization); 159 | ``` 160 | 161 | Or, for a single channel: 162 | 163 | ```php 164 | use App\Models\Organization; 165 | use App\Notifications\InvoicePaid; 166 | 167 | //... 168 | 169 | $organization = Organization::find(1); 170 | 171 | $user->unsubscribe(InvoicePaid::class, 'mail', $organization); 172 | ``` 173 | 174 | Next, we need a way to retrieve the `Organization` when your notification is sent. Add a function called `getSubscriptionModel` to your notification class to tell it how to retrieve the model: 175 | 176 | ```php 177 | invoice = $invoice; 188 | } 189 | 190 | public function getSubscriptionModel($notifiable) 191 | { 192 | return $this->invoice->organization; 193 | } 194 | } 195 | ``` 196 | 197 | Now, when this notification gets sent, it will check for the model scope and apply it if necessary. You can add your own logic to `getSubscriptionModel` and even return `null` in cases you don't want to scope the subscription. 198 | 199 | ### Resetting scoped subscriptions 200 | 201 | To reset the notifications on a scoped subscription: 202 | 203 | ```php 204 | use App\Models\Organization; 205 | use App\Notifications\InvoicePaid; 206 | 207 | //... 208 | 209 | $organization = Organization::find(1); 210 | 211 | $user->resetSubscriptions(InvoicePaid::class, $organization); 212 | ``` 213 | 214 | ### Retrieving scoped subscriptions 215 | 216 | Retrieve subscriptions related to a certain model: 217 | 218 | ```php 219 | use App\Models\Organization; 220 | 221 | //... 222 | 223 | $organization = Organization::find(1); 224 | 225 | $user->notificationSubscriptions()->model($organization); 226 | ``` 227 | 228 | ## Advanced usage 229 | 230 | ### Ignoring subscriptions 231 | 232 | If you'd like the package to ignore your notification entirely, and skip any suppressions, set the public `$ignoreSubscriptions` property to true in your notification class: 233 | 234 | ```php 235 | ignoreSubscriptions = $ignore; 246 | } 247 | } 248 | ``` 249 | 250 | ```php 251 | use App\Notifications\InvoicePaid; 252 | 253 | $user->notify(new InvoicePaid($invoice, true)); //This will always get sent. 254 | ``` 255 | 256 | ### Excluding channels 257 | 258 | You may want to exclude certain channels from being considered when checking for unsubscribes. By default, we already exclude the `database` channel. You can configure this in the configuration file: 259 | 260 | ```php 261 | ['database'], 266 | 267 | ]; 268 | ``` 269 | 270 | ## Resolution logic 271 | 272 | The package uses the following logic to resolve whether or not to send a notification: 273 | 274 | 1. If `channel` is in `excluded_channels`, send the notification. 275 | 2. If the notification has the public property `$ignoreSubscriptions` set to `true`, send the notification. 276 | 3. Attempt to retrieve a record for the particular channel, if none is found, attempt to retrieve a record for all channels (i.e. `"*"`). 277 | 278 | 3a. If there is no record, and the channel is not opt-in, send the notification. 279 | 280 | 3b. If there is a record, send the notification based on the status of the subscription (subscribed or unsubscribed). 281 | 282 | ## License 283 | Released under the [MIT](https://choosealicense.com/licenses/mit/) license. See [LICENSE](LICENSE.md) for more information. 284 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "liran-co/laravel-notification-subscriptions", 3 | "description": "Notification subscription management.", 4 | "homepage": "https://github.com/liran-co/laravel-notification-subscriptions", 5 | "keywords": [ 6 | "laravel", 7 | "subscription", 8 | "subscriptions", 9 | "notification", 10 | "notifications" 11 | ], 12 | "license": "MIT", 13 | "authors": [ 14 | { 15 | "name": "Liran Cohen", 16 | "email": "l@liran.co" 17 | } 18 | ], 19 | "require": { 20 | "php": "^7.2.5|^8.0|^8.1", 21 | "laravel/framework": "^6.0|^7.0|^8.0|^9.0|^10.0|^11.0" 22 | }, 23 | "autoload": { 24 | "psr-4": { 25 | "LiranCo\\NotificationSubscriptions\\": "src" 26 | } 27 | }, 28 | "extra": { 29 | "laravel": { 30 | "providers": [ 31 | "LiranCo\\NotificationSubscriptions\\NotificationSubscriptionsServiceProvider" 32 | ] 33 | } 34 | }, 35 | "minimum-stability": "dev", 36 | "prefer-stable": true 37 | } 38 | -------------------------------------------------------------------------------- /config/notification-subscriptions.php: -------------------------------------------------------------------------------- 1 | ['database'], 6 | 7 | ]; 8 | -------------------------------------------------------------------------------- /database/migrations/2020_05_20_000001_create_notification_subscriptions_table.php: -------------------------------------------------------------------------------- 1 | increments('id'); 13 | $table->string('type'); 14 | $table->string('channel'); 15 | $table->morphs('notifiable'); 16 | $table->nullableMorphs('model'); 17 | $table->timestamp('unsubscribed_at')->nullable(); 18 | $table->timestamps(); 19 | }); 20 | } 21 | 22 | public function down() 23 | { 24 | Schema::dropIfExists('notification_subscriptions'); 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /src/Events/NotificationSuppressed.php: -------------------------------------------------------------------------------- 1 | event = $event; 23 | 24 | $this->notification = $event->notification; 25 | 26 | $this->notifiable = $event->notifiable; 27 | 28 | $this->channel = $event->channel; 29 | } 30 | } -------------------------------------------------------------------------------- /src/Listeners/NotificationSendingListener.php: -------------------------------------------------------------------------------- 1 | notifiable))) { 14 | return $event; 15 | } 16 | 17 | if (in_array($event->channel, config('notification-subscriptions.excluded_channels'))) { 18 | return $event; 19 | } 20 | 21 | if ($event->notification->ignoreSubscriptions ?? false) { 22 | return $event; 23 | } 24 | 25 | $model = null; 26 | if (method_exists($event->notification, 'getSubscriptionModel')) { 27 | $model = $event->notification->getSubscriptionModel($event->notifiable); 28 | } 29 | 30 | $optin = []; 31 | if (method_exists($event->notification, 'getOptInSubscriptions')) { 32 | $optin = $event->notification->getOptInSubscriptions(); 33 | } 34 | 35 | $subscribed = $event->notifiable->isSubscribed(get_class($event->notification), $event->channel, $model, $optin); 36 | 37 | if (!$subscribed) { 38 | event(new NotificationSuppressed($event)); 39 | return false; 40 | } 41 | 42 | return $event; 43 | } 44 | } 45 | -------------------------------------------------------------------------------- /src/Models/NotificationSubscription.php: -------------------------------------------------------------------------------- 1 | 'datetime', 17 | ]; 18 | 19 | public function notifiable() 20 | { 21 | return $this->morphTo(); 22 | } 23 | 24 | public function model() 25 | { 26 | return $this->morphTo(); 27 | } 28 | 29 | public function scopeModel($query, $model = null) 30 | { 31 | return $query->where('model_type', $model ? get_class($model) : null)->where('model_id', optional($model)->id); 32 | } 33 | 34 | public function isSubscribed() 35 | { 36 | return is_null($this->unsubscribed_at); 37 | } 38 | 39 | public function unsubscribe() 40 | { 41 | $this->forceFill(['unsubscribed_at' => $this->freshTimestamp()])->save(); 42 | } 43 | 44 | public function resubscribe() 45 | { 46 | $this->forceFill(['unsubscribed_at' => null])->save(); 47 | } 48 | } 49 | -------------------------------------------------------------------------------- /src/NotificationSubscriptionsServiceProvider.php: -------------------------------------------------------------------------------- 1 | publishes([ 12 | __DIR__.'/../config/notification-subscriptions.php' => config_path('notification-subscriptions.php'), 13 | ]); 14 | 15 | $this->loadMigrationsFrom(__DIR__.'/../database/migrations'); 16 | } 17 | 18 | public function register() 19 | { 20 | $this->mergeConfigFrom( 21 | __DIR__.'/../config/notification-subscriptions.php', 22 | 'notification-subscriptions' 23 | ); 24 | 25 | $this->app->register(\LiranCo\NotificationSubscriptions\Providers\EventServiceProvider::class); 26 | } 27 | } 28 | -------------------------------------------------------------------------------- /src/Providers/EventServiceProvider.php: -------------------------------------------------------------------------------- 1 | [ 11 | 'LiranCo\NotificationSubscriptions\Listeners\NotificationSendingListener', 12 | ], 13 | ]; 14 | 15 | public function boot() 16 | { 17 | parent::boot(); 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /src/Traits/HasNotificationSubscriptions.php: -------------------------------------------------------------------------------- 1 | morphMany(NotificationSubscription::class, 'notifiable'); 12 | } 13 | 14 | public function subscribe($type, $channel = '*', $model = null) 15 | { 16 | $subscription = $this->findSubscription($type, $channel, $model); 17 | 18 | if ($subscription) { 19 | return $subscription->resubscribe(); 20 | } 21 | 22 | return $this->createSubscription($type, $channel, $model); 23 | } 24 | 25 | public function unsubscribe($type, $channel = '*', $model = null) 26 | { 27 | $subscription = $this->findSubscription($type, $channel, $model); 28 | 29 | if ($subscription) { 30 | return $subscription->unsubscribe(); 31 | } 32 | 33 | return $this->createSubscription($type, $channel, $model, true); 34 | } 35 | 36 | public function findSubscription($type, $channel = '*', $model = null) 37 | { 38 | return $this->notificationSubscriptions()->where('type', $type)->where('channel', $channel)->model($model)->first(); 39 | } 40 | 41 | public function createSubscription($type, $channel = '*', $model = null, $unsubscribe = false) 42 | { 43 | return $this->notificationSubscriptions()->create([ 44 | 'type' => $type, 45 | 'channel' => $channel, 46 | 'model_type' => $model ? get_class($model) : null, 47 | 'model_id' => optional($model)->id, 48 | 'unsubscribed_at' => $unsubscribe ? $this->freshTimestamp() : null, 49 | ]); 50 | } 51 | 52 | public function isSubscribed($type, $channel, $model = null, $optin = []) 53 | { 54 | $subscription = $this->findSubscription($type, $channel, $model) ?: $this->findSubscription($type, '*', $model); 55 | 56 | if (!$subscription) { 57 | return !in_array($channel, $optin); 58 | } 59 | 60 | return $subscription->isSubscribed(); 61 | } 62 | 63 | public function resetSubscriptions($type, $model = null) 64 | { 65 | $this->notificationSubscriptions()->where('type', $type)->model($model)->delete(); 66 | 67 | return $this; 68 | } 69 | } 70 | --------------------------------------------------------------------------------