README

此包旨在帮助您以最少的5分钟设置时间处理电子邮件取消订阅。安装后，您发送的电子邮件通知应包含在页脚和邮件头中的取消订阅链接，以便电子邮件客户端可以向用户展示以便快速取消订阅。它还可以通过签名路由/控制器处理用户的取消订阅。

安装

您可以通过composer安装此包

composer require ylsideas/subscribable-notifications

为了使用内置的取消订阅处理器，您可以发布应用程序服务提供程序。如果您希望实现自己的取消订阅流程并且只想将取消订阅链接插入到通知中，您可以选择不执行此操作。

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

这将创建一个\App\Providers\SubscriberServiceProvider类，您需要在config/app.php中进行注册。

'providers' => [
    ...
    
    /*
     * Package Service Providers...
     */
     \App\Providers\SubscribableServiceProvider::class,
     
     ...
]

之后，您可以通过服务提供程序中的方法快速配置取消订阅处理器，这些方法返回闭包。

包本身不决定您如何存储或评估用户的订阅状态。相反，它提供了用于处理此操作的钩子。

使用方法

首先，您必须在您的通知User模型上实现YlsIdeas\SubscribableNotifications\Contracts\CanUnsubscribe接口。您还可以应用YlsIdeas\SubscribableNotifications\MailSubscriber特质，这将为您自动提供由该库提供的取消订阅控制器的签名URL。

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

class User implements CanUnsubscribe
{
    use Notifiable, MailSubscriber;
}

实现自己的取消订阅链接

如果您希望实现自己的完全不同的unsubscribeLink()方法，您可以。

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)
        );
    }
}

将通知作为邮件列表的一部分实现

如果您希望将特定的邮件列表应用于通知，您需要在那些通知上实现YlsIdeas\SubscribableNotifications\Contracts\AppliesToMailingList。这将把两个取消订阅链接放入由那些通知生成的电子邮件中。一个适用于所有电子邮件，另一个仅适用于那种类型的电子邮件。

use YlsIdeas\SubscribableNotifications\Contracts\AppliesToMailingList;

class Welcome extends Notification implements AppliesToMailingList
{
    ...
    
    public function usesMailingList(): string
    {
        return 'weekly-updates';
    }
    
    ...
}

使用完整的取消订阅工作流程

使用App\Providers\SubscriberServiceProvider，您可以设置简单的钩子来处理从所有未来电子邮件中取消用户订阅。此包不决定您应该如何存储取消订阅未来电子邮件的记录。相反，您在提供程序中提供函数，这些函数将被调用。以下只是您可以做的示例。

为特定邮件列表实现取消订阅钩子

如果用户通过链接取消特定邮件列表的订阅，此处理器将被调用。

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

为所有电子邮件实现取消订阅钩子

如果用户点击了取消订阅所有未来电子邮件的链接，此处理器将被调用。

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

实现取消订阅响应

在用户取消订阅后，完成处理器将被调用，允许您自定义用户被重定向到的位置，或者如果您想显示更多的表单。

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

专用处理器

您还可以提供一个格式为class@method的字符串，订阅类将使用它从服务容器中获取类，然后在需要执行更自定义操作的情况下调用指定的方法。

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

检查是否根据订阅发送通知

您还可以添加钩子来检查用户是否应该接收邮件列表或所有邮件通知的通知。

要完成这个任务，您需要确保您的用户实现了YlsIdeas\SubscribableNotifications\Contracts\CheckSubscriptionStatusBeforeSendingNotifications接口。YlsIdeas\SubscribableNotifications\MailSubscriber特性将为您实现这一功能，以便您可以使用内置的订阅者处理程序。

如果您想自己实现检查订阅的方法，可以像下面的示例一样自己实现这个方法。

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
        );
    }
}

然后，您需要在应该触发检查用户收到的订阅状态的邮件通知上实现YlsIdeas\SubscribableNotifications\Contracts\CheckNotifiableSubscriptionStatus接口。然后，只需在需要检查订阅状态时返回true即可。

use YlsIdeas\SubscribableNotifications\Contracts\CheckNotifiableSubscriptionStatus;

class Welcome extends Notification implements CheckNotifiableSubscriptionStatus
{
    ...
    
    public function checkMailSubscriptionStatus() : bool
    {
        return true;
    }
    
    ...
}

要使用这项功能，您需要添加自己的订阅检查钩子。这些钩子可以按照您的需要进行实现。

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;
        };
    }
    
    ...
}

自定义电子邮件模板

默认情况下，生成的电子邮件使用相同的模板，只是在电子邮件的页脚注入了一小段文本。如果您想进一步自定义模板，可以发布视图。

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

这将创建一个包含html.blade.php和text.blade.php的resources/views/vendor/subscriber文件夹，这些文件可以自定义。然后，这些文件将成为通知邮件通道的默认使用模板。

自定义用户模型

如果您使用的是与app/Models/User.php或Laravel 7及更早版本中的app/Users.php不同的用户模型，您可以通过调用来更改它。建议您在SubscriberServiceProvider的boot方法中这样做。

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

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全

如果您发现任何安全相关的问题，请通过电子邮件peter.fox@ylsideas.co联系，而不是使用问题跟踪器。

ylsideas / subscribable-notifications

维护者

详情