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.

nikolaposa / notify

Maintainers

Details