README

此模块提供了一种通过多种投递渠道发送通知的方法，包括邮件、屏幕、短信（通过Nexmo）等。通知也可以存储在数据库中，以便在您的Web界面中显示。

通知是简短的消息，用于通知用户应用程序中发生的事情。例如，如果您正在编写一个账单应用程序，您可能通过电子邮件和短信渠道向用户发送“发票已支付”的通知。

要求

PHP 7.1+
- gmp
- mbstring
- curl
- openssl
建议使用PHP 7.2+以获得更好的性能。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令：

php composer.phar require --prefer-dist webzop/yii2-notifications "*"

或者在您的 composer.json 文件的 require 部分添加以下内容：

"webzop/yii2-notifications": "*"

用法

通知通常用作应用程序模块，并在应用程序配置中进行配置，如下所示

[
    'modules' => [
        'notifications' => [
            'class' => 'webzop\notifications\Module',
            'channels' => [
                'screen' => [
                    'class' => 'webzop\notifications\channels\ScreenChannel',
                ],
                'email' => [
                    'class' => 'webzop\notifications\channels\EmailChannel',
                    'message' => [
                        'from' => 'example@email.com'
                    ],
                ],
                'web' => [
                    'class' => 'webzop\notifications\channels\WebChannel',
                    'enable' => true,                                       // OPTIONAL (default: true) enable/disable web channel
                    'config' => [
                        'serviceWorkerFilepath' => '/service-worker.js',    // OPTIONAL (default: /service-worker.js) is the service worker filename
                        'serviceWorkerScope' => '/app',                     // OPTIONAL (default: './' the service worker path) the scope of the service worker: https://developers.google.com/web/ilt/pwa/introduction-to-service-worker#registration_and_scope
                        'serviceWorkerUrl' => 'url-to-serviceworker',       // OPTIONAL (default: Url::to(['/notifications/web-push-notification/service-worker']))
                        'subscribeUrl' => 'url-to-subscribe-handler',       // OPTIONAL (default: Url::to(['/notifications/web-push-notification/subscribe']))
                        'unsubscribeUrl' => 'url-to-unsubscribe-handler',   // OPTIONAL (default: Url::to(['/notifications/web-push-notification/unsubscribe']))
                        'subscribeLabel' => 'subscribe button label',       // OPTIONAL (default: 'Subscribe')
                        'unsubscribeLabel' => 'subscribe button label',     // OPTIONAL (default: 'Unsubscribe')
                    ],
                    'auth' => [
                        'VAPID' => [
                            'subject' => 'mailto:me@website.com',           // can be a mailto: or your website address
                            'publicKey' => '~88 chars',                     // (recommended) uncompressed public key P-256 encoded in Base64-URL
                            'privateKey' => '~44 chars',                    // (recommended) in fact the secret multiplier of the private key encoded in Base64-URL
                            'pemFile' => 'path/to/pem',                     // if you have a PEM file and can link to it on your filesystem
                            'pem' => 'pemFileContent',                      // if you have a PEM file and want to hardcode its content
                            'reuseVAPIDHeaders' => true                     // OPTIONAL (default: true) you can reuse the same JWT token them for the same flush session to boost performance using
                        ],
                    ],
                ],
            ],
        ],
    ],
];

要启用Web推送通知，浏览器需要验证您的身份。VAPID标准可以验证所有浏览器的应用程序。您需要为您的服务器创建并提供公钥和私钥。这些密钥必须安全存储，并且不应更改。

如果您想禁用Web推送通知，只需将标志 'notifications.web.enable' 设置为 false。

要生成未压缩的公钥和私钥，以Base64编码，请在您的Linux bash中输入以下内容：

$ openssl ecparam -genkey -name prime256v1 -out private_key.pem
$ openssl ec -in private_key.pem -pubout -outform DER|tail -c 65|base64|tr -d '=' |tr '/+' '_-' >> public_key.txt
$ openssl ec -in private_key.pem -outform DER|tail -c +8|head -c 32|base64|tr -d '=' |tr '/+' '_-' >> private_key.txt

或者您可以使用模块中提供的方法

\Minishlink\WebPush\VAPID::createVapidKeys();

创建通知

每个通知由一个类表示（通常存储在app/notifications目录中）。

namespace app\notifications;

use Yii;
use webzop\notifications\Notification;

class AccountNotification extends Notification
{
    const KEY_NEW_ACCOUNT = 'new_account';

    const KEY_RESET_PASSWORD = 'reset_password';

    /**
     * @var \yii\web\User the user object
     */
    public $user;

    /**
     * @inheritdoc
     */
    public function getTitle(){
        switch($this->key){
            case self::KEY_NEW_ACCOUNT:
                return Yii::t('app', 'New account {user} created', ['user' => '#'.$this->user->id]);
            case self::KEY_RESET_PASSWORD:
                return Yii::t('app', 'Instructions to reset the password');
        }
    }

    /**
     * @inheritdoc
     */
    public function getRoute(){
        return ['/users/edit', 'id' => $this->user->id];
    }
}

发送通知

创建通知后，您可以按以下方式发送它：

$user = User::findOne(123);

AccountNotification::create(AccountNotification::KEY_RESET_PASSWORD, ['user' => $user])->send();

指定投递渠道

每个通知类都有一个 shouldSend($channel) 方法，用于确定通知将在哪些类型和渠道上发送。在此示例中，通知将在所有渠道上发送，除了“屏幕”或带有“new_account”键。

/**
 * Get the notification's delivery channels.
 * @return boolean
 */
public function shouldSend($channel)
{
    if($channel->id == 'screen'){
        if(!in_array($this->key, [self::KEY_NEW_ACCOUNT])){
            return false;
        }
    }
    return parent::shouldSend($channel);
}

可以通过通知的 renotification_time 属性限制发送给用户的具有相同键/用户的相同通知的数量。只有在此属性指定的期间内没有发送其他具有相同用户/键的通知时，才会发送新的通知。renotification_time 必须是 DateInterval::__constructor() 接受的字符串。

// For example to limit to 1 notification per hour
$notification = AccountNotification::create(AccountNotification::KEY_RESET_PASSWORD, ['user' => $user]);
$notification->renotification_time = 'PT1H';
$notification->send();

指定特定渠道的发送

每个渠道都有一个接收通知实例并定义该渠道发送通知方式的方法。但是，您可以通过在通知类中定义 toMail ("to" + [Channel ID]) 来覆盖发送方法。以下示例演示了如何操作。

/**
 * Override send to email channel
 *
 * @param $channel the email channel
 * @return void
 */
public function toEmail($channel){
    switch($this->key){
        case self::KEY_NEW_ACCOUNT:
            $subject = 'Welcome to MySite';
            $template = 'newAccount';
            break;
        case self::KEY_RESET_PASSWORD:
            $subject = 'Password reset for MySite';
            $template = 'resetPassword';
            break;
    }

    $message = $channel->mailer->compose($template, [
        'user' => $this->user,
        'notification' => $this,
    ]);
    Yii::configure($message, $channel->message);

    $message->setTo($this->user->email);
    $message->setSubject($subject);
    $message->send($channel->mailer);
}

自定义渠道

此模块提供了一些预构建的渠道，但您可能需要编写自己的渠道来发送通知。为此，您需要定义一个包含 send 方法的类

namespace app\channels;

use webzop\notifications\Channel;
use webzop\notifications\Notification;

class VoiceChannel extends Channel
{
    /**
     * Send the given notification.
     *
     * @param Notification $notification
     * @return void
     */
    public function send(Notification $notification)
    {
        // use $notification->getTitle() ou $notification->getDescription();
        // Send your notification in this channel...
    }

}

您还应该在您的应用程序配置中配置渠道

[
    'modules' => [
        'notifications' => [
            'class' => 'webzop\notifications\Module',
            'channels' => [
                'voice' => [
                    'class' => 'app\channels\VoiceChannel',
                ],
                //...
            ],
        ],
    ],
]

屏幕渠道

此渠道用于显示类似于上图预览的小通知。通知将存储在数据库中，因此在使用此渠道之前，您必须运行其迁移脚本

./yii migrate/up --migrationPath=vendor/webzop/yii2-notifications/migrations/

因此，您可以在您的应用程序布局中调用 Notifications 小部件以显示生成的通知

<div class="header">
    ...
    <?php echo \webzop\notifications\widgets\Notifications::widget() ?>

</div>

Web推送通知渠道

此通道用于向订阅者发送网页推送通知。每个通知订阅都将存储在数据库中，因此在使用此通道之前，您必须运行其迁移脚本。

./yii migrate/up --migrationPath=vendor/webzop/yii2-notifications/migrations/

因此，您可以在您的应用程序布局中调用 Notifications 小部件以显示生成的通知

<div>
    <?php echo \webzop\notifications\widgets\WebNotifications::widget() ?>
</div>

您可以根据以下方式自定义小部件的HTML模板。将模板设置为false将隐藏所有小部件HTML，浏览器会提示用户允许通知。如果您自定义HTML模板，请记得包括一个id为'js-web-push-subscribe-button'的按钮。

<div>
    <?= \webzop\notifications\widgets\WebNotifications::widget([
        'template' => '... <button id="js-web-push-subscribe-button" disabled="disabled"></button> ...'
    ]) ?>
</div>

请记住，为了在初始化WebNotifications小部件时提供服务工作者，将service-worker.js文件放置在网站根目录中。

overplex / yii2-notifications

维护者

详细信息