A library for handling and processing notifications
A library for handling and processing notifications.
To install the package, you simply run:
composer require emmanix2002/notifier
The notifier works using the the following concepts:
- 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
Notifierclass, or to individual Channels.
- Processors added to the
Notifierclass are called before the message and recipients are passed to the Channels; while
- Processors added to a
Channelare passed the message and recipients before they're passed to the Handlers
- Processors added to the
- Message: a message, is an instance of
Emmanix2002\Notifier\Message\MessageInterfaceis 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
Collectionof one item. This collection should be an instance of
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
This is the expected flow for using the notifier:
- 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
- Create your
Message(for instance, you could create an
- Create your
Recipient(e.g. for SMS, we need a phone number, we could say
$recipients = new RecipientCollection(['2348123456789'], PhoneRecipient::class);)
- Call your
So it flows like:
Notifier -> (Processors) -> Channels -> (Processors) -> Handlers
(Processors) appear twice, here's why:
- The first is triggered for processors added to the
- The second is triggered for processors added to the
A message is an instance of
encapsulates the data that is to be sent out to the recipients.
A few message types are provided by default:
Emmanix2002\Notifier\Message\EmailMessage: this is a basic email message implementation, providing this such as:
Bodyfields. 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
EmailMessageclass, this class is the basic implementation for an sms text message. It has only one field:
message, which is the
stringcontaining the message.
Emmanix2002\Notifier\Message\InfobipSmsMessage: this implementation is a more advanced version of the
SmsMessageclass, providing special properties (or fields) unique to the Infobip system. It extends
SmsMessageproviding many other fields like:
notifyUrl(for delivery reports),
notifyContentType(the content type used to represent the delivery report), and
\DateTimeinstance representing when the message should be sent - scheduling SMS)
Emmanix2002\Notifier\Message\SendgridEmailMessage: this also is an advanced implementation of the
EmailMessageclass. It extends it and also provides a few additional properties unique to Sendgrid like:
sections, and even
category(for tagging the message(s)).
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
recipient is an instance of
Emmanix2002\Notifier\Recipient\RecipientInterface; all recipients are expected to
implement this interface.
Some default recipient classes are provided with the package:
recipientis useful for addressing phone numbers; a simple array of strings can be passed to the
RecipientCollectionto create this. For example:
$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
The first parameter of the
RecipientCollection constructor supports 3 forms:
An array of strings e.g.
$collection = new RecipientCollection(['firstname.lastname@example.org', ...], EmailRecipient::class);
when looping through (or when accessing an index -
$collection- it returns an instance of the second argument which is a class that implements
It does so by passing each
stringelement of the array as the first argument of the class recipient constructor.
An array of
RecipientInterfaceinstances. You can see this from the
Even though it's an array of
RecipientInterfaceinstances, you still need to pass the second parameter.
Like before, when looping or accessing an offset of the collection, you'll get a
An array with a form representing the constructor form of the desired
RecipientInterfaceimplementation. Take a look at the
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.
Each of the files inside the
examples directory highlight these 2 forms. So, feel free to create your own
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
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.
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.
RecipientCollection) should be
passed to the next handler for processing:
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
AbstractHandler class return
false - meaning they don't propagate.
examples directory for more.