Generic notification library

[thomasjthomasj]

Came up when brainstorming improvements to the CMS blog comment improvements (mothership-ec/cog-mothership-cms#240), I wrote a basic specification as to what it might entail:

---

• User notification will involve building a generic Notification library in Cog.
• This library will have a NotificationInterface, which will have methods required for sending an email:
  • getToEmail()
  • getFromEmail()
  • getBody()
  • getSubject()
• We will build a new class under comments called CommentNotification that will implement the NotificationInterface. This will be instanciated using a CommentNotificationFactory that exists in the service container, and will take a Comment as its constructor argument.
• In Cog there will be a Notifier class that exists in the service container and has a notify() method, which uses the Mailer library to send an appropriate notification.
• The resulting event listener would look something like this:

$comment = $event->getComment();

$this->get('notifier')->notify(
    $this->get('cms.blog.comment_notification_factory')->getNotification($comment)
);

---

However, after discussion with Sam, perhaps the bulk of the logic should go to the notifier library rather than individual classes within the different modules. Things to consider:

• How do we work out what type of object gets sent to which email addresses
• Should we use adapter classes to make it possible to send non-email notifications in the future (HipChat, flash messages, etc.)?
• What if we want to notify an entire user group? Logic for this would not belong in Cog but rather would belong in User, or perhaps we should make an entirely new module for notifications? Doing so would mean that we would also need to make extra modules for comment notifications, order notifications etc. etc.

[kuiche]

I suggest classes: NotifierCollection, Notification, NotifierInterface, and implementation specific EmailNotifier.

NotifierCollection extends Message\Cog\ValueObject\Collection
{
  /**
   * Sends notification using notifiers with keys in $notifers or to all if
   * $notifiers is not set.
   * 
   * Defaults to null to send to all in the collection. Useful if we wish to
   * multiple collections in services for different occasions. For example
   * we could have 'notifiers.error' for notifying errors. This may be extended
   * in the site/other modules to send error notifications to extra places.
   */
  public function notify(array $notifiers = null)
  {...}
}

/**
 * Simple notification struct. Holds a title and a message. Title used for things
 * like subject in email etc. There may be other fields we would like to have in here.
 */
Notification
{
  $title;
  $message;
}

NotifierInterface
{
  /**
   * Notify method. the specific implementation logic happens here
   */
  public function notify(Notification $n);

  /**
   * Get the unique name of the notifier (used as a key)
   */
  public function getName();
}

EmailNotifier implements NotifierInterface
{
  /**
   * Construct with the name of the notifier
   */
  public function __construct($name)
  {...}

  /**
   * Set to email
   */
  public function setTo($to)
  {...}

  /**
   * Set from email
   */
  public function setFrom($from)
  {...}

  /**
   * Set cc
   */
  public function setCC($cc)
  {...}

  /**
   * {@inheritDoc}
   */
  public function getName()
  {/* Get the name */ ... }

  /**
   * {@inheritDoc}
   */
  public function notify($from)
  {/* Notify logic */ ... }
}

Then with these classes we may set up notifier collections for different purposes. For example in we will want a way to notify users about orders, so we could have:

$services['notifiers.user_notifications'] = function ($c) {
  return new NotifierCollection([
    (new EmailNotifier('user_email'))
      ->setTo($c['...'])
      ->setFrom($c['...']),
  ]);
};

Then we may notify from, say, a controller by:

$n = new Notification();
$n->title = "Notification Title (Email subject etc)";
$n->message = "Notification Message";

$this->get('notifiers.user_notifications')->notify($n);