Notifier
![Software License][ico-license]
![Total Downloads][ico-downloads], (*1)
A library for handling and processing notifications., (*2)
Installation
To install the package, you simply run:, (*3)
composer require emmanix2002/notifier
Introduction
The notifier works using the the following concepts:, (*4)
-
Channels: channels are named groupings of handlers which receive a message and a list of recipients
-
Handlers: handlers are instances of
Emmanix2002\Notifier\Handler\HandlerInterface, which
are tied to channels, and are passed the message and recipients for delivery.
-
Processors: processors are callable that are passed the message and recipients for processing,
before they're passed to the relevant channels or handlers. Processors are used to filter or make
adjustments to the message or recipients before they are passed down to the channel. Processors can
be added to the main
Notifier class, or to individual Channels.
-
Processors added to the
Notifier class are called before the message and recipients are passed
to the Channels; while
-
Processors added to a
Channel are passed the message and recipients before they're passed to the
Handlers
-
Message: a message, is an instance of
Emmanix2002\Notifier\Message\MessageInterface is the
information that requires sending to recipients.
-
Recipients: by default, the
notify() methods expect a list of recipients; even if you only need to
send a message to a single recipient, you still need to provide an Collection of one item. This
collection should be an instance of Emmanix2002\Notifier\Recipient\RecipientCollection.
By default, 2 handlers are provided to get you started:
- InfobipSmsHandler: for sending SMS messages using the Infobip API
- SendgridEmailHandler: for sending email messages using the Sendgrid API, (*5)
Process Flow
This is the expected flow for using the notifier:, (*6)
- Create an instance of
Notifier (you can use the Notifier::instance() to have a shared instance through the application)
-
(optional) Add one or more Processors to the
Notifier
- Create your
Message (for instance, you could create an SmsMessage)
- Create your
Recipient (e.g. for SMS, we need a phone number, we could say $recipients = new RecipientCollection(['2348123456789'], PhoneRecipient::class);)
- Call your
Notifier::notify($message, $recipients)
So it flows like:, (*7)
Notifier -> (Processors) -> Channels -> (Processors) -> Handlers
You see (Processors) appear twice, here's why:
- The first is triggered for processors added to the Notifier; while
- The second is triggered for processors added to the Channel, (*8)
Message
A message is an instance of Emmanix2002\Notifier\Message\MessageInterface. A MessageInterface implementation
encapsulates the data that is to be sent out to the recipients., (*9)
A few message types are provided by default:
- Emmanix2002\Notifier\Message\EmailMessage: this is a basic email message implementation, providing this such as:
Bcc, Cc, Subject, ReplyTo, From and Body fields. Any handler processing emails should be able to get all
information required for creating the email from an instance of this class.
- Emmanix2002\Notifier\Message\SmsMessage: just like the EmailMessage class, this class is the basic implementation
for an sms text message. It has only one field: message, which is the string containing the message.
- Emmanix2002\Notifier\Message\InfobipSmsMessage: this implementation is a more advanced version of the SmsMessage
class, providing special properties (or fields) unique to the Infobip system. It extends SmsMessage providing many
other fields like: notifyUrl (for delivery reports), notifyContentType (the content type used to represent the
delivery report), and scheduleFor (a \DateTime instance representing when the message should be sent - scheduling SMS)
- Emmanix2002\Notifier\Message\SendgridEmailMessage: this also is an advanced implementation of the EmailMessage
class. It extends it and also provides a few additional properties unique to Sendgrid like: templateId, sections,
and even category (for tagging the message(s))., (*10)
Recipient Collection
The RecipientCollection represents a list/collection of destinations that the notification should be sent to; it
also tries to understand how to interpret each of these addresses (it does so from the second __construct() parameter)., (*11)
A recipient is an instance of Emmanix2002\Notifier\Recipient\RecipientInterface; all recipients are expected to
implement this interface., (*12)
Some default recipient classes are provided with the package:
- Emmanix2002\Notifier\Recipient\PhoneRecipient: this recipient is useful for addressing phone numbers; a simple
array of strings can be passed to the RecipientCollection to create this. For example:, (*13)
$phones = ['2348123456789', '23481223456789'];
$collection = new RecipientCollection($phones, PhoneRecipient::class);
// see the examples/sms-notify.php file for the full example
As you can see with this, the destination address is simply an array of `strings`.
Emmanix2002\Notifier\Recipient\EmailRecipientEmmanix2002\Notifier\Recipient\SendgridEmailRecipient
The first parameter of the RecipientCollection constructor supports 3 forms:, (*14)
-
An array of strings e.g. $collection = new RecipientCollection(['email@domain.com', ...], EmailRecipient::class);
when looping through (or when accessing an index - $collection[0] - it returns an instance of the second argument
which is a class that implements RecipientInterface).
It does so by passing each string element of the array as the first argument of the class recipient constructor., (*15)
-
An array of RecipientInterface instances. You can see this from the examples/email-notify.php example file.
Even though it's an array of RecipientInterface instances, you still need to pass the second parameter.
Like before, when looping or accessing an offset of the collection, you'll get a RecipientInterface instance., (*16)
-
An array with a form representing the constructor form of the desired RecipientInterface implementation. Take a
look at the examples/email-notify-using-address-array.php example.
This form is the most flexible because it allows you to keep your code simple and clean, without having to create
too many objects until you really need to.
It splits the array and passes the indexes as the arguments to the __construct() method of the instance. For instance,
it passes index 0 as the first parameter, index 1 as the second parameter, and so forth., (*17)
Each of the files inside the examples directory highlight these 2 forms. So, feel free to create your own
RecipientInterface implementations., (*18)
Handlers
Handlers are instances of HandlerInterface (see Introduction). When you create a channel, you
either pass the handlers in the constructor, or you add them one at a time on the created Channel., (*19)
Handlers are the actual mechanism that send out the notifications; without handlers, a channel basically does nothing.
Handlers added to a channel are stored in a stack (i.e. Last-In, First-Out - LIFO); meaning, the last handler added
to a channel gets executed first., (*20)
After a handler is called, and it completes execution, it returns either a boolean value or any other value as
required, that informs the notifier whether or not the request (i.e. Message and RecipientCollection) should be
passed to the next handler for processing:, (*21)
-
boolean (true or false): the request should be forwarded (true) to the next handler, else (false) it should not
-
mixed: any other value besides the boolean (true) causes the notifier to stop at this handler, and return
this value. This is useful in scenarios where the actual response from the handler is important.
Handlers must define a propagate(): bool method on themselves to describe the propagate preference for the handler.
By default, all handlers that extend the AbstractHandler class return false - meaning they don't propagate., (*22)
Usage
See the examples directory for more., (*23)
Wallogit.com
