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.
You can install the package via composer:
composer require ylsideas/subscribable-notificationsOptionally 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-providerThis 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.
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;
}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)
);
}
}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 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.
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();
};
}
...
}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();
};
}
...
}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');
};
}
...
} 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';
}
...
}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;
};
}
...
} 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-viewsThis 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.
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');composer testPlease see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email peter.fox@ylsideas.co instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.
This package was generated using the Laravel Package Boilerplate.