README

Notifier

处理和通知的库。

• 安装
• 介绍
• 流程
• 消息
• 收件人集合
• 处理器
• 用法

安装

要安装此包，您只需运行

composer require emmanix2002/notifier

介绍

通知器通过以下概念工作

• 通道：通道是接收消息和收件人列表的处理器的命名分组。
• 处理器：处理器是绑定到通道的Emmanix2002\Notifier\Handler\HandlerInterface实例，传递消息和收件人进行交付。
• 处理器：处理器是传递消息和收件人进行处理的调用，在它们传递到相关通道或处理器之前。处理器用于在传递到通道之前过滤或调整消息或收件人。处理器可以添加到主Notifier类或单个通道。
  • 添加到Notifier类的处理器在消息和收件人传递到通道之前调用；而
  • 添加到Channel的处理器在传递给处理器之前传递消息和收件人
• 消息：消息是Emmanix2002\Notifier\Message\MessageInterface的实例，是需要发送给收件人的信息。
• 收件人：默认情况下，notify()方法期望一个收件人列表；即使您只需要向单个收件人发送消息，您也仍然需要提供一个包含一个项目的Collection。此集合应该是Emmanix2002\Notifier\Recipient\RecipientCollection的实例。

默认情况下，提供了2个处理器以供您开始使用

• InfobipSmsHandler：用于使用Infobip API发送短信消息
• SendgridEmailHandler：用于使用Sendgrid API发送电子邮件消息

流程

这是使用通知器的预期流程

1. 创建Notifier实例（您可以使用Notifier::instance()在应用程序中通过共享实例使用）
2. (可选) 向Notifier添加一个或多个处理器
3. 创建您的Message（例如，您可以创建一个SmsMessage）
4. 创建您的Recipient（例如，对于短信，我们需要一个电话号码，我们可以说$recipients = new RecipientCollection(['2348123456789'], PhoneRecipient::class);）
5. 调用您的Notifier::notify($message, $recipients)

因此，流程如下

Notifier -> (Processors) -> Channels -> (Processors) -> Handlers

您看到(Processors)出现了两次，原因如下

• 第一个是为添加到Notifier的处理器触发的；而
• 第二个是为添加到Channel的处理器触发的

消息

消息是Emmanix2002\Notifier\Message\MessageInterface的实例。一个MessageInterface实现封装了要发送给收件人的数据。

默认情况下提供了一些消息类型

• Emmanix2002\Notifier\Message\EmailMessage：这是一个基本的电子邮件消息实现，提供以下字段：Bcc、Cc、Subject、ReplyTo、From和Body。任何处理电子邮件的处理程序应该能够从一个此类实例中获取创建电子邮件所需的所有信息。
• Emmanix2002\Notifier\Message\SmsMessage：与EmailMessage类类似，此类是短信文本消息的基本实现。它只有一个字段：message，这是一个包含消息的string。
• Emmanix2002\Notifier\Message\InfobipSmsMessage：这是SmsMessage类的更高级版本，提供了Infobip系统特有的特殊属性（或字段）。它扩展了SmsMessage，提供了许多其他字段，如：notifyUrl（用于投递报告）、notifyContentType（用于表示投递报告的内容类型）和scheduleFor（表示消息应发送时间的\DateTime实例 - 安排短信）。
• Emmanix2002\Notifier\Message\SendgridEmailMessage：这也是EmailMessage类的更高级实现。它扩展了它，并提供了一些Sendgrid特有的附加属性，如：templateId、sections，甚至还有category（用于标记消息）。

收件人集合

RecipientCollection表示一个列表/集合，其中包含通知应该发送到的destinations；它还试图理解如何解释这些地址（它从第二个__construct()参数中这样做）。

recipient是Emmanix2002\Notifier\Recipient\RecipientInterface的实例；所有接收者都应实现此接口。

该软件包提供了一些默认接收者类。

• Emmanix2002\Notifier\Recipient\PhoneRecipient：这个recipient对于处理电话号码很有用；可以通过将简单的字符串数组传递给RecipientCollection来创建此。例如

    $phones = ['2348123456789', '23481223456789'];
    $collection = new RecipientCollection($phones, PhoneRecipient::class);
    // see the examples/sms-notify.php file for the full example
  

  如你所见，目标地址只是一个字符串数组。

• Emmanix2002\Notifier\Recipient\EmailRecipient

• Emmanix2002\Notifier\Recipient\SendgridEmailRecipient

RecipientCollection构造函数的第一个参数支持3种形式

1. 字符串数组，例如$collection = new RecipientCollection(['email@domain.com', ...], EmailRecipient::class);
   当遍历（或在访问索引时 - $collection[0] - 它返回第二个参数的实例，该参数是一个实现RecipientInterface的类）。
   它是通过将数组中的每个string元素作为类接收者构造函数的第一个参数传递来完成的。

2. 一组RecipientInterface实例。您可以从examples/email-notify.php示例文件中看到这一点。
   尽管它是一个RecipientInterface实例的数组，但您仍然需要传递第二个参数。
   像以前一样，当遍历或访问集合的偏移量时，您会得到一个RecipientInterface实例。

3. 一个表示所需RecipientInterface实现构造函数形式的数组。请参阅examples/email-notify-using-address-array.php示例。
   这种形式是最灵活的，因为它允许您保持代码简单和整洁，无需在真正需要之前创建太多的对象。
   它将数组拆分，并将索引作为参数传递给实例的__construct()方法。例如，它将索引0作为第一个参数传递，将索引1作为第二个参数，依此类推。

示例目录中的每个文件都突出了这两种形式。因此，您可以自由地创建自己的RecipientInterface实现。

处理器

处理器是HandlerInterface的实例（请参阅介绍）。当您创建一个通道时，您可以在构造函数中传递处理器，或者逐个将它们添加到创建的Channel中。

处理器是发送通知的实际机制；没有处理器，通道基本上什么都不做。
添加到通道中的处理器存储在堆栈中（即后进先出 - LIFO），这意味着最后添加到通道的处理器将首先执行。

处理器被调用并完成执行后，它返回一个 boolean 值或其他所需的任何值，以通知通知器是否应将请求（即 Message 和 RecipientCollection）传递给下一个处理器进行处理

• boolean （true 或 false）：请求应（true）转发给下一个处理器，否则（false）不应转发
• mixed：除了 boolean （true）之外的其他任何值都会使通知器在此处理器处停止，并返回此值。这在实际响应对处理器很重要的情况下很有用。

处理器必须在自身上定义一个 propagate(): bool 方法来描述处理器的传播偏好。
默认情况下，所有扩展 AbstractHandler 类的处理器都 返回 false - 意味着 它们不传播。

用法

有关更多信息，请参阅 examples 目录。