PHPackages                             ylsideas/subscribable-notifications - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. ylsideas/subscribable-notifications

ActiveLibrary[Mail & Notifications](/categories/mail)

ylsideas/subscribable-notifications
===================================

A Laravel package for adding unsubscribe links to notifications

v1.7.0(1y ago)193135.0k↓10.6%10[2 PRs](https://github.com/ylsideas/subscribable-notifications/pulls)MITPHPPHP ^8.2CI passing

Since Jun 20Pushed 2mo ago7 watchersCompare

[ Source](https://github.com/ylsideas/subscribable-notifications)[ Packagist](https://packagist.org/packages/ylsideas/subscribable-notifications)[ Docs](https://github.com/ylsideas/subscribable-notifications)[ GitHub Sponsors](https://github.com/peterfox)[ RSS](/packages/ylsideas-subscribable-notifications/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (10)Versions (33)Used By (0)

Subscribable Notifications for Laravel
======================================

[](#subscribable-notifications-for-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/0af63abfee89e64c9b315835b5c9daab2c522ca9e8e4e359cf23f7c4b626f1e7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f796c7369646561732f737562736372696261626c652d6e6f74696669636174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ylsideas/subscribable-notifications)[![GitHub Tests Action Status](https://camo.githubusercontent.com/70a449a8b9b030c5fe4f7632684d7a881e9b8c081b34e39ece63a2e4adbef69e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f796c7369646561732f737562736372696261626c652d6e6f74696669636174696f6e732f72756e2d74657374733f6c6162656c3d7465737473)](https://github.com/ylsideas/subscribable-notifications/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/a24a6ea10a2ba2dc52005c1274fc08a2522a5663b45c514d67eaca272c977703/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f796c7369646561732f737562736372696261626c652d6e6f74696669636174696f6e732f436865636b253230262532306669782532307374796c696e673f6c6162656c3d636f64652532307374796c65)](https://github.com/ylsideas/subscribable-notifications/actions?query=workflow%3A%22Check+%26+fix+styling%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/30ac4b9b23bee0d30a7eb15d9970e68ad72426229bc3748a6e9348d60f68e213/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f796c7369646561732f737562736372696261626c652d6e6f74696669636174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ylsideas/subscribable-notifications)

This package has been designed to help you handle email unsubscribes with as little as 5 minutes setup. After installing your notifications sent over email should now be delivered with unsubscribe links in the footer and as a mail header which email clients can present to the user for quicker unsubscribing. It can also handle resolving the unsubscribing of the user through a signed route/controller.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require ylsideas/subscribable-notifications
```

Optionally to make use of the built in unsubscribing handler you can publish the application service provider. If you wish to implement your own unsubscribing process and only insert unsubscribe links into your notifications, you can forgo doing this.

```
php artisan vendor:publish --tag=subscriber-provider
```

This will create a `\App\Providers\SubscriberServiceProvider` class which you will need to register in `config/app.php`.

```
'providers' => [
    ...

    /*
     * Package Service Providers...
     */
     \App\Providers\SubscribableServiceProvider::class,

     ...
]
```

After this you can configure your unsubscribe handlers quickly as methods within the service provider that return the closures.

The package itself does not determine how you store or evaluate your users' subscribed state. Instead it provides hooks in which to handle that.

Usage
-----

[](#usage)

First off you must implement the `YlsIdeas\SubscribableNotifications\Contracts\CanUnsubscribe` interface on your notifiable User model. You can also apply the `YlsIdeas\SubscribableNotifications\MailSubscriber` trait which will implement this for you to automatically provide signed urls for the unsubscribe controller provided by this library.

```
use YlsIdeas\SubscribableNotifications\MailSubscriber;
use YlsIdeas\SubscribableNotifications\Contracts\CanUnsubscribe;

class User implements CanUnsubscribe
{
    use Notifiable, MailSubscriber;
}
```

### Implementing your own unsubscribe links

[](#implementing-your-own-unsubscribe-links)

If you wish to implement your own completely different `unsubscribeLink()` method you can.

```
use YlsIdeas\SubscribableNotifications\Contracts\CanUnsubscribe;

class User implements CanUnsubscribe
{
    use Notifiable;

    public function unsubscribeLink(?string $mailingList = ''): string
    {
        return URL::signedRoute(
            'sorry-to-see-you-go',
            ['subscriber' => $this, 'mailingList' => $mailingList],
            now()->addDays(1)
        );
    }
}
```

### Implementing notifications as part of a mailing list

[](#implementing-notifications-as-part-of-a-mailing-list)

If you wish to apply specific mailing lists to notifications you need to implement the `YlsIdeas\SubscribableNotifications\Contracts\AppliesToMailingList` on those notifications. This will put two unsubscribe links into your emails generated from those notifications. One for all emails and one for only that type of email.

```
use YlsIdeas\SubscribableNotifications\Contracts\AppliesToMailingList;

class Welcome extends Notification implements AppliesToMailingList
{
    ...

    public function usesMailingList(): string
    {
        return 'weekly-updates';
    }

    ...
}
```

### Using the full unsubscribing workflow

[](#using-the-full-unsubscribing-workflow)

Using the `App\Providers\SubscriberServiceProvider` you can set up simple hooks to handle unsubscribing the user from all future emails. This package doesn't determine how you should store that record of opting out of future emails. Instead you provide functions in the provider which will be called. The following are just examples of what you can do.

#### Implementing an unsubscribe hook for a specific mailing list

[](#implementing-an-unsubscribe-hook-for-a-specific-mailing-list)

This handler will be called if a user links a link through to unsubscribe for a specific mailing list.

```
public class SubscriberServiceProvider
{
    ...

    public function onUnsubscribeFromMailingList()
    {
        return function ($user, $mailingList) {
            $user->mailing_lists = $user->mailing_lists->put($mailingList, false);
            $user->save();
        };
    }

    ...
}
```

#### Implementing an unsubscribe hook for all emails

[](#implementing-an-unsubscribe-hook-for-all-emails)

This handler will be called if the user has clicked through to the link to unsubscribe from all future emails.

```
public class SubscriberServiceProvider
{
    ...

    public function onUnsubscribeFromAllMailingLists()
    {
        return function ($user) {
            $user->unsubscribed_at = now();
            $user->save();
        };
    }

    ...
}
```

#### Implementing an unsubscribe response

[](#implementing-an-unsubscribe-response)

The completion handler will be called after a user is unsubscribed, allowing you to customise where the user is redirected to or if you want to maybe show a further form even.

```
public class SubscriberServiceProvider
{
    ...

    public function onCompletion()
    {
        return function ($user, $mailingList) {
            return view('confirmation')
                ->with('alert', 'You\'re not unsubscribed');
        };
    }

    ...
}
```

### Dedicated handler

[](#dedicated-handler)

You may also provide a string in the format of `class@method` that the subscriber class will use to grab the class from the service container and then call the specified method on if you want to do something more custom.

```
public class SubscriberServiceProvider
{
    ...

    public function onUnsubscribeFromAllMailingLists()
    {
        return '\App\UnsubscribeHandler@handleUnsubscribing';
    }

    ...
}
```

### Checking if a notification should be sent per the subscription

[](#checking-if-a-notification-should-be-sent-per-the-subscription)

You can also add hooks to check if a user should receive notifications for a mailing list or for all mail notifications.

To do this you need to make sure your user has the `YlsIdeas\SubscribableNotifications\Contracts\CheckSubscriptionStatusBeforeSendingNotifications` interface implemented. The `YlsIdeas\SubscribableNotifications\MailSubscriber` trait will implement this for you to use the built in Subscriber handlers.

If you want to implement a method yourself to check the subscription you could also just implement the method yourself like in the example below.

```
use YlsIdeas\SubscribableNotifications\Contracts\CanUnsubscribe;
use YlsIdeas\SubscribableNotifications\Contracts\CheckSubscriptionStatusBeforeSendingNotifications;
use YlsIdeas\SubscribableNotifications\Facades\Subscriber;

class User implements CanUnsubscribe, CheckSubscriptionStatusBeforeSendingNotifications
{
    use Notifiable;

    public function mailSubscriptionStatus(Notification $notification) : bool
    {
        return Subscriber::checkSubscriptionStatus(
            $this,
            $notification instanceof AppliesToMailingList
                ? $notification->usesMailingList()
                : null
        );
    }
}
```

Then you need to implement the `YlsIdeas\SubscribableNotifications\Contracts\CheckNotifiableSubscriptionStatus` interface on the notifications that should trigger a check of the subscription status of the user it's being sent to. Then you just need to return `true` if the subscription status should be checked.

```
use YlsIdeas\SubscribableNotifications\Contracts\CheckNotifiableSubscriptionStatus;

class Welcome extends Notification implements CheckNotifiableSubscriptionStatus
{
    ...

    public function checkMailSubscriptionStatus() : bool
    {
        return true;
    }

    ...
}
```

To use the functionality you then need to add your own Subscription check hooks. These hooks can be implemented as you see fit.

```
public class SubscriberServiceProvider
{
    ...

    public function onCheckSubscriptionStatusOfMailingList()
    {
        return function ($user, $mailingList) {
            return $user->mailing_lists->get($mailingList, false);
        };
    }

    public function onCheckSubscriptionStatusOfAllMailingLists()
    {
        return function ($user) {
            return $user->unsubscribed_at === null;
        };
    }

    ...
}
```

### Customising the email templates

[](#customising-the-email-templates)

Out of the box the emails generated use the same templates except that they inject a small bit of text into the footer of the emails. If you wish you customise the templates further you may publish the views.

```
php artisan vendor:publish --tag=subscriber-views
```

This will create a `resources/views/vendor/subscriber` folder containing both `html.blade.php`and `text.blade.php` which can be customised. These will then be the defaults used by the notification mail channel.

### Customising the User Model

[](#customising-the-user-model)

If you are using a different User model than the one found in `app/Models/User.php` or `app/Users.php` for Laravel 7 and earlier you can change this by calling. It's suggested you do this in the boot method of the `SubscriberServiceProvider`.

```
Subscriber::userModel('App\Models\User');
```

### Testing

[](#testing)

```
composer test
```

### Changelog

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

### Security

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Peter Fox](https://github.com/peterfox)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

Laravel Package Boilerplate
---------------------------

[](#laravel-package-boilerplate)

This package was generated using the [Laravel Package Boilerplate](https://laravelpackageboilerplate.com).

###  Health Score

59

—

FairBetter than 99% of packages

Maintenance68

Regular maintenance activity

Popularity49

Moderate usage in the ecosystem

Community20

Small or concentrated contributor base

Maturity82

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 52.9% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~173 days

Recently: every ~280 days

Total

13

Last Release

438d ago

PHP version history (6 changes)1.0.0PHP ^7.1

1.0.1PHP ^7.2

1.2.0PHP ^7.2.5

v1.3.0PHP ^8.0|^7.3

v1.5.0PHP ^8.0|^7.4

v1.6.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/0b739c85248a287e7318fd7098806a90c5b8aa7e91d99e493628597eee6520e9?d=identicon)[YlsIdeas](/maintainers/YlsIdeas)

---

Top Contributors

[![peterfox](https://avatars.githubusercontent.com/u/1716506?v=4)](https://github.com/peterfox "peterfox (46 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (24 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (12 commits)")[![arjasco](https://avatars.githubusercontent.com/u/8780549?v=4)](https://github.com/arjasco "arjasco (2 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (1 commits)")[![gavinservai](https://avatars.githubusercontent.com/u/6363022?v=4)](https://github.com/gavinservai "gavinservai (1 commits)")[![trkyshorty](https://avatars.githubusercontent.com/u/4043309?v=4)](https://github.com/trkyshorty "trkyshorty (1 commits)")

---

Tags

laravelylsideasunsubscribable-notification

###  Code Quality

TestsPest

Static AnalysisPHPStan

### Embed Badge

![Health badge](/badges/ylsideas-subscribable-notifications/health.svg)

```
[![Health](https://phpackages.com/badges/ylsideas-subscribable-notifications/health.svg)](https://phpackages.com/packages/ylsideas-subscribable-notifications)
```

###  Alternatives

[laravel-notification-channels/telegram

Telegram Notifications Channel for Laravel

1.1k3.4M35](/packages/laravel-notification-channels-telegram)[mckenziearts/laravel-notify

Flexible flash notifications for Laravel

1.7k1.1M5](/packages/mckenziearts-laravel-notify)[propaganistas/laravel-disposable-email

Disposable email validator

5762.6M6](/packages/propaganistas-laravel-disposable-email)[xammie/mailbook

Laravel Mail Explorer

482458.3k1](/packages/xammie-mailbook)[spatie/laravel-notification-log

Log notifications sent by your Laravel app

207902.8k](/packages/spatie-laravel-notification-log)[vormkracht10/laravel-mails

Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app.

24149.7k](/packages/vormkracht10-laravel-mails)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)