nikolaposa / notifier
Extensible library for building notifications and sending them via different delivery channels.
Installs: 1 574
Dependents: 0
Suggesters: 0
Security: 0
Stars: 21
Watchers: 5
Forks: 3
Open Issues: 0
Requires
- php: ^7.2
- guzzlehttp/guzzle: ^6.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.1
- phpstan/phpstan: ^0.12.10
- phpstan/phpstan-phpunit: ^0.12.6
- phpunit/phpunit: ^8.0
README
Extensible library for building notifications and sending them via different delivery channels.
Installation
The preferred method of installation is via Composer. Run the following command to install
the latest version of a package and add it to your project's composer.json
:
composer require nikolaposa/notifier
Theory of operation
Notifications are informative messages that are sent through different channels (i.e. email, SMS, mobile push) to notify users about certain events in the application. Notification is a higher-level abstraction, a concept that encapsulates a subject to be notified to the recipient, regardless of delivery channels through which that information can be communicated. From an architectural standpoint, notification is a domain concern.
In order to minimize the coupling of your domain with the infrastructure for sending notifications, Notifier library was based on on unobtrusive interfaces that should be implemented by your objects in order to plug them into the workflow of the library. Those are:
Notification
- marks the object as a notification that can be used with the Notifier library,Recipient
- represents the recipient of the notification which provides contact (i.e. email address, phone number) for a certain channel; typically implemented by a User domain object.
For each channel through which Notification is supposed to be sent, Notification class should implement channel-specific
interface, making the Notification suitable for sending via a specific channel. These interfaces declare message
building methods, for example EmailNotification::toEmailMessage()
, that convert the notification to a message sent by
that particular channel. Channel-specific Notification interfaces extend the Notification
interface itself, so you do
not need to implement it explicitly.
Channel component captures implementation details of how a Notification is sent via certain delivery channels. Specific channel implementation typically consists of:
- channel-specific Notification interface,
- Message class - transport-level message to which Notification gets converted,
Channel
implementation responsible for the very act of sending the Notification.
Out of the box, this library features facilities for sending notifications via email and SMS. The highly extensible design allows for implementing custom delivery channels.
Finally, Notifier
service is a facade that manages the entire process of sending a Notification to a list of
Recipients via supported channels. It is the only service of this library that the calling code is supposed to interact
with directly.
Usage
Creating Notifications
namespace App\Model; use Notifier\Channel\Email\EmailMessage; use Notifier\Channel\Sms\SmsMessage; use Notifier\Channel\Email\EmailNotification; use Notifier\Channel\Sms\SmsNotification; use Notifier\Recipient\Recipient; class TodoExpiredNotification implements EmailNotification, SmsNotification { /** @var Todo */ protected $todo; public function __construct(Todo $todo) { $this->todo = $todo; } public function toEmailMessage(Recipient $recipient): EmailMessage { return (new EmailMessage()) ->from('noreply@example.com') ->subject('Todo expired') ->htmlBody( 'Dear ' . $recipient->getRecipientName() . ',' . '<br><br>' . 'Your todo: <b>' . $this->todo->getText() . '</b> has expired.' ); } public function toSmsMessage(Recipient $recipient): SmsMessage { return (new SmsMessage()) ->text('Todo: ' . $this->todo->getText() . ' has expired'); } }
Implementing Recipient
namespace App\Model; use Notifier\Recipient\Recipient; class User implements Recipient { /** @var string */ protected $name; /** @var array */ protected $contacts; public function __construct(string $name, array $contacts) { $this->name = $name; $this->contacts = $contacts; } public function getName(): string { return $this->name; } public function getRecipientContact(string $channel, Notification $notification): ?string { return $this->contacts[$channel] ?? null; } public function getRecipientName(): string { return $this->name; } }
Sending Notifications
use Notifier\Channel\Channels; use Notifier\Channel\Email\EmailChannel; use Notifier\Channel\Email\SimpleMailer; use Notifier\Channel\Sms\SmsChannel; use Notifier\Channel\Sms\TwilioTexter; use Notifier\Notifier; use Notifier\Recipient\Recipients; $notifier = new Notifier(new Channels( new EmailChannel(new SimpleMailer()), new SmsChannel(new TwilioTexter('auth_id', 'auth_token')) )); $notifier->send( new TodoExpiredNotification($todo), new Recipients($user1, $user2, $user3) );
Credits
License
Released under MIT License - see the License File for details.