README

此 Yii2 扩展支持通过多种交付渠道发送通知，包括邮件、短信、Slack、Telegram 等。通知还可以存储在数据库中，以便在您的网页界面中显示。

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

安装

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

运行以下命令之一

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

或

"tuyakhov/yii2-notifications": "*"

将以下内容添加到您的 composer.json 文件的 require 部分中。

用法

以下示例演示了如何创建 Notifier 实例并发送第一条通知

$notifier = new \tuyakhov\notifications\Notifier([
  'channels' => [...],
]);
$notifier->send($recipients, $notifications);

Notifier 通常用作应用程序组件，并按以下方式配置在应用程序配置中

[
   'components' => [
       'notifier' => [
           'class' => '\tuyakhov\notifications\Notifier',
           'channels' => [
               'mail' => [
                   'class' => '\tuyakhov\notifications\channels\MailChannel',
                   'from' => 'no-reply@example.com'
               ],
               'sms' => [
                   'class' => '\tuyakhov\notifications\channels\TwilioChannel',
                   'accountSid' => '...',
                   'authToken' => '...',
                   'from' => '+1234567890'
               ],
               'telegram' => [
                    'class' => '\tuyakhov\notifications\channels\TelegramChannel',
                    'botToken' => '...'
                ],
               'database' => [
                    'class' => '\tuyakhov\notifications\channels\ActiveRecordChannel'
               ]
           ],
       ],
   ],
]

一旦组件配置完成，就可以用于发送通知

$recipient = User::findOne(1);
$notification = new InvoicePaid($invoice);

Yii::$app->notifier->send($recipient, $notification);

每个通知类应实现 NotificationInterface，并包含一个 viaChannels 方法以及多个消息构建方法（如 exportForMail），这些方法将通知转换为针对该特定渠道优化的消息。以下是一个支付发票时通知的示例

use tuyakhov\notifications\NotificationInterface;
use tuyakhov\notifications\NotificationTrait;

class InvoicePaid implements NotificationInterface
 {
    use NotificationTrait;
    
    private $invoice;
    
    public function __construct($invoice) 
    {
        $this->invoice = $invoice;
    }

    /**
     * Prepares notification for 'mail' channel
     */
    public function exportForMail() {
        return Yii::createObject([
           'class' => '\tuyakhov\notifications\messages\MailMessage',
           'view' => ['html' => 'invoice-paid'],
           'viewData' => [
               'invoiceNumber' => $this->invoice->id,
               'amount' => $this->invoice->amount
           ]
        ])
    }
    
    /**
     * Prepares notification for 'sms' channel
     */
    public function exportForSms()
    {
        return \Yii::createObject([
            'class' => '\tuyakhov\notifications\messages\SmsMessage',
            'text' => "Your invoice #{$this->invoice->id} has been paid"
        ]);
    }
    
    /**
     * Prepares notification for 'database' channel
     */
    public function exportForDatabase()
    {
        return \Yii::createObject([
            'class' => '\tuyakhov\notifications\messages\DatabaseChannel',
            'subject' => "Invoice has been paid",
            'body' => "Your invoice #{$this->invoice->id} has been paid",
            'data' => [
                'actionUrl' => ['href' => '/invoice/123/view', 'label' => 'View Details']
            ]
        ]);
    }
 }

您可以在任何模型上使用 NotifiableInterface 和 NotifiableTrait

use yii\db\ActiveRecord;
use tuyakhov\notifications\NotifiableTrait;
use tuyakhov\notifications\NotifiableInterface;

class User extends ActiveRecord implements NotifiableInterface 
{
   use NotifiableTrait;
   
   public function routeNotificationForMail() 
   {
        return $this->email;
   }
}

数据库通知

database 通知渠道将通知信息存储在数据库表中。
您可以通过查询表来在应用程序的用户界面中显示通知。但在这样做之前，您需要创建一个数据库表来存储您的通知。为此，您可以使用此扩展提供的迁移

yii migrate --migrationPath=@vendor/tuyakhov/yii2-notifications/src/migrations

或

'controllerMap' => [
    ...
    'migrate' => [
        'class' => 'yii\console\controllers\MigrateController',
        'migrationNamespaces' => [
            'tuyakhov\notifications\migrations',
        ],
    ],
    ...
],

php yii migrate/up

访问通知
一旦通知存储在数据库中，您需要一种方便的方法从可通知实体访问它们。此扩展附带的 NotifiableTrait 包含一个返回实体通知的通知关系。要获取通知，您可以像访问任何其他 ActiveRecord 关系一样访问此方法。

$model = User::findOne(1);
foreach($model->notifications as $notification) {
    echo $notification->subject;
}

如果您只想检索“未读”通知，则可以使用 unreadNotifications 关系。

$model = User::findOne(1);
foreach($model->unreadNotifications as $notification) {
    echo $notification->subject;
}

您可以通过 DatabaseMessage 添加的描述通知的自定义 JSON 数据进行访问

/** @var $notificatiion tuyakhov\notifications\models\Notificatios */
$actionUrl = $notification->data('actionUrl'); // ['href' => '/invoice/123/pay', 'label' => 'Pay Invoice']

标记通知为已读
通常，当用户查看通知时，您会想将其标记为“已读”。Notification 模型中的 ReadableBehavior 提供了一个 markAsRead 方法，该方法更新通知数据库记录中的 read_at 列

$model = User::findOne(1);
foreach($model->unreadNotifications as $notification) {
    $notification->markAsRead();
    
    // the following methods are also available
    $notification->markAsUnread();
    $notification->isUnread();
    $notification->isRead();
}