update readme

README.md

@@ -29,30 +29,75 @@ to the require section of your `composer.json` file.
 Usage
 -----
 
-Once the extension is installed, simply use it in your code by  :
+The following example shows how to create a Notifier instance and send your first notification:
 
-Widget
+```php
+$notifier = new \tuyakhov\notifications\Notifier([
+  'channels' => [...],
+]);
+$notifier->send($recipients, $notifications);
+```
+
+Notifier is often used as an application component and configured in the application configuration like the following:
 
 ```php
-    \tuyakhov\notifications\EmbedWidget::widget([
-        'code' => 'vs5ZF9fRDzA',
-        'playerParameters' => [
-            'controls' => 2
-        ],
-        'iframeOptions' => [
-            'width' => '600',
-            'height' => '450'
-        ]
-    ]);
+[
+   'components' => [
+       'notifier' => [
+           'class' => '\tuyakhov\notifications\Notifier',
+           'channels' => [
+               'mail' => [
+                   'class' => 'MailChannel',
+                   'from' => '[email protected]'
+               ]
+           ],
+       ],
+   ],
+]
 ```
 
-Validator
+Each notification class should implement NotificationInterface and contains a via method and a variable number of message building methods (such as `exportForMail`) that convert the notification to a message optimized for that particular channel.
+Example of notification that covers the case when an invoice has been paid:
 
 ```php
-    public function rules()
+use tuyakhov\notifications\NotificationInterface;
+
+class InvoicePaid implements NotificationInterface
+ {
+    private $invoice;
+
+    public function __cunstruct($invoice) 
+    {
+        $this->invoice = $invoice
+    }
+
+    public function exportForMail() {
+        return Yii::createObject([
+           'class' => 'tuyakhov\notifications\messages\MailMessage',
+           'view' => ['html' => 'invoice-paid'],
+           'viewData' => [
+               'invoiceNumber' => $this->invoice->id,
+               'amount' => $this->invoice->amount
+           ]
+        ])
+    }
+ }
+```
+
+You may use the NotifiableInterface and NotifiableTrait on any of your models:
+
+ ```php
+ use yii\db\ActiveRecord;
+ use tuyakhov\notifications\NotifiableTrait;
+ use tuyakhov\notifications\NotifiableInterface;
+
+ class User extends ActiveRecord implements NotifiableInterface 
+ {
+    use NotifiableTrait;
+
+    public function routeNotificationForMail() 
     {
-        return [
-            ['notifications_code', CodeValidator::className()],
-        ];
+         return $this->email;
     }
-```
+ }
+ ```

src/NotifiableBehavior.php

@@ -7,11 +7,27 @@
 
 
 use yii\base\Behavior;
+use yii\base\Event;
+use yii\di\Instance;
 
 class NotifiableBehavior extends Behavior
 {
     public $notifications = [];
 
+    /**
+     * @var Notifier
+     */
+    public $notifier = 'notifier';
+
+    public function init()
+    {
+        parent::init();
+        $this->notifier = Instance::of($this->notifier);
+    }
+
+    /**
+     * @inheritdoc
+     */
     public function attach($owner)
     {
         $this->owner = $owner;
@@ -20,11 +36,14 @@ public function attach($owner)
                 $notifications = [$notifications];
             }
             foreach ($notifications as $notification) {
-                $owner->on($event, is_string($notification) ? [$notification, 'handle'] : $notification);
+                $owner->on($event, [$this, 'handle'], ['notification' => $notification]);
             }
         }
     }
 
+    /**
+     * @inheritdoc
+     */
     public function detach()
     {
         if ($this->owner) {
@@ -33,12 +52,39 @@ public function detach()
                     $notifications = [$notifications];
                 }
                 foreach ($notifications as $notification) {
-                    $this->owner->off($event, is_string($notification) ? [$notification, 'handle'] : $notification);
+                    $this->owner->off($event, [$this, 'handle']);
                 }
             }
             $this->owner = null;
         }
     }
 
+    /**
+     * Handles the event using public properties.
+     * @param Event $event
+     * @throws \InvalidArgumentException
+     * @throws \RuntimeException
+     */
+    public function handle(Event $event)
+    {
+        if (!isset($event->data['notification'])) {
+            throw new \InvalidArgumentException('Can not find `notification` in event data');
+        }
+        if (!$this->owner instanceof NotifiableInterface) {
+            throw new \RuntimeException('Owner should implement `NotifiableInterface`');
+        }
+        $notification = $event->data['notification'];
+        $config = [];
+        foreach (get_object_vars($event) as $param) {
+            $config[$param] = $event->$param;
+        }
+        $config['class'] = $notification;
+        /**
+         * @var $notification NotificationInterface
+         */
+        $notification = \Yii::createObject($config);
+        $this->notifier->send($this->owner, $notification);
+    }
+
 
 }

src/NotifiableTrait.php

@@ -10,11 +10,39 @@
 
 trait NotifiableTrait
 {
-    public function shouldSendNotification(NotificationInterface $notification)
+    /**
+     * Determines if notifiable entity should receive the notification by checking in notification settings.
+     * @param NotificationInterface $notification
+     * @return bool
+     */
+    public function shouldReceiveNotification(NotificationInterface $notification)
     {
-
+        $notificationAlias = Inflector::camel2id(get_class($notification));
+        if (isset($this->notificationSettings[$notificationAlias])) {
+            return (bool) $this->notificationSettings[$notificationAlias];
+        }
+        return true;
+    }
+
+    /**
+     * Send notifications via email by default
+     * @return array
+     */
+    public function viaChannels()
+    {
+        return ['mail'];
     }
 
+    /**
+     * Return the notification routing information for the given channel.
+     * ```php
+     * public function routeNotificationForMail() {
+     *      return $this->email;
+     * }
+     * ```
+     * @param $channel string
+     * @return mixed
+     */
     public function routeNotificationFor($channel)
     {
         if (method_exists($this, $method = 'routeNotificationFor'.Inflector::id2camel($channel))) {

src/NotificationInterface.php

@@ -11,12 +11,14 @@
 interface NotificationInterface
 {
     /**
+     * Export notification as message for given channel.
      * @param string $channel
      * @return AbstractMessage
      */
     public function exportFor($channel);
 
     /**
+     * Determines on which channels the notification will be delivered
      * @return array
      */
     public function broadcastOn();

src/NotificationTrait.php

@@ -5,10 +5,14 @@
 
 namespace tuyakhov\notifications;
 
+use tuyakhov\notifications\messages\AbstractMessage;
 use yii\helpers\Inflector;
 
-class NotificationTrait implements NotificationInterface
+trait NotificationTrait
 {
+    /**
+     * @return array
+     */
     public function broadcastOn()
     {
         $channels = [];
@@ -21,12 +25,27 @@ public function broadcastOn()
         return $channels;
     }
 
+    /**
+     * Determines on which channels the notification will be delivered.
+     * ```php
+     * public function exportForMail() {
+     *      return Yii::createObject([
+     *          'class' => 'tuyakhov\notifications\messages\MailMessage',
+     *          'view' => ['html' => 'welcome'],
+     *          'viewData' => [...]
+     *      ])
+     * }
+     * ```
+     * @param $channel
+     * @return AbstractMessage
+     * @throws \InvalidArgumentException
+     */
     public function exportFor($channel)
     {
         if (method_exists($this, $method = 'exportFor'.Inflector::id2camel($channel))) {
             return $this->{$method}();
         }
-        throw new \InvalidArgumentException("Cannot find message export for chanel `{$channel}`");
+        throw new \InvalidArgumentException("Can not find message export for chanel `{$channel}`");
     }
 
 }

src/Notifier.php

@@ -29,7 +29,7 @@
  *              'class' => '\tuyakhov\notifications\Notifier',
  *              'channels' => [
  *                  'mail' => [
- *                      'class' => 'EmailNotificationChannel',
+ *                      'class' => 'MailChannel',
  *                  ]
  *              ],
  *          ],
@@ -47,7 +47,7 @@ class Notifier extends Component
      * ```php
      * [
      *     'mail' => [
-     *         'class' => 'EmailNotificationChannel',
+     *         'class' => 'MailChannel',
      *     ],
      * ]
      * ```