From 556d662e2b28122a3a065f865fc5a54828af92b5 Mon Sep 17 00:00:00 2001
From: Kartik Visweswaran <kartikv2@gmail.com>
Date: Thu, 19 Oct 2017 10:29:27 +0530
Subject: [PATCH] Fix #91: Add Documentation for Mail events

---
 CHANGELOG.md                            |   1 +
 docs/events/mail-events.md              | 101 ++++++++++++++++++++++++
 src/User/Controller/AdminController.php |   2 +-
 3 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 docs/events/mail-events.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0d09491..f52b255 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## 1.0.14 - Work in progress
 
+- Enh #91: Documentation for Mail events (kartik-v)
 - Enh #79: Enhancements to Mailer exception handling and events (kartik-v)
 - Fix #85: External links should open in a new tab|window (eseperio)
 - Enh #23: Provide administrator with an option to reset user password (tonydspaniard)
diff --git a/docs/events/mail-events.md b/docs/events/mail-events.md
new file mode 100644
index 0000000..b6efa03
--- /dev/null
+++ b/docs/events/mail-events.md
@@ -0,0 +1,101 @@
+Mail Events
+===========
+
+The following is the list of the mail events and where they happen:
+
+On Models
+---------
+
+- **User**
+    - `MailEvent::EVENT_BEFORE_SEND_MAIL`: triggered before a mail is sent
+    - `MailEvent::EVENT_AFTER_SEND_MAIL`: triggered after a mail is sent
+
+Mail Event Getter Methods
+-------------------------
+
+Each of the events above would receive the following properties via getter methods:
+  
+1. `getType()`: _string_, returns the type of mailer sent. The following mailer types will be returned:
+    - `MailEvent::TYPE_WELCOME` or `'welcome'`: when a welcome mailer is sent on user creation or registration signup. 
+    - `MailEvent::TYPE_RECOVERY` or `'recovery'`: when a password reset / recovery mailer is sent.
+    - `MailEvent::TYPE_CONFIRM` or `'confirm'`: when an account confirmation mailer is sent.
+    - `MailEvent::TYPE_RECONFIRM` or `'reconfirm'`: when an account confirmation mailer is requested for resending.
+- `getUser()`: _Da\User\Model\User_, returns the current user model
+- `getMailService()`: _Da\User\Service\MailService_, returns the mail service instance
+- `getException()`: _Exception_, returns the exception object instance in case a mailer sending exception is received. 
+   This will be `NULL` if no exception is received. It will also always be `NULL` for `MailEvent::EVENT_BEFORE_SEND_MAIL`
+   and any exception received will only be trapped via `MailEvent::EVENT_AFTER_SEND_MAIL`.
+
+How to Work With Mail Events
+----------------------------
+
+All these events receive an instance of `Da\User\Event\MailEvent`. The Event receives an instance of a `Da\Model\User` 
+class and the other getter method properties as listed earlier, that you could use for whatever logic you wish to implement. 
+
+The recommended way to make use of events is by creating a new file in your config folder (i.e. `events.php`), configure 
+there all your events and then include that file on your 
+[`entry script`](http://www.yiiframework.com/doc-2.0/guide-structure-entry-scripts.html).
+
+Here is an example of setting an event for the `User` model: 
+
+```php 
+<?php 
+// events.php file
+
+use Da\User\Event\MailEvent;
+use Da\User\Model\User;
+use yii\base\Event;
+
+// BEFORE MAIL IS SENT: This will happen at the model's level
+Event::on(User::class, MailEvent::EVENT_BEFORE_SEND_MAIL, function (MailEvent $event) {
+
+    $user = $event->getUser();
+    $type = $event->getType();
+    $mailService = $event->getMailService();
+    
+    // ... your logic here
+}
+
+// AFTER MAIL IS SENT: This will happen at the model's level
+Event::on(User::class, MailEvent::EVENT_AFTER_SEND_MAIL, function (MailEvent $event) {
+
+    $user = $event->getUser();
+    $type = $event->getType();
+    $mailService = $event->getMailService();
+    $exception = $event->getException(); // fetches exception received if any
+    
+    // ... your logic here based on exception received for example
+    if ($exception !== null) {
+        // do something
+    }
+}
+```
+
+Now, the only thing I need to do is adding the `events.php` file to your entry script (i.e. `index.php`). The following 
+is taken from the Yii 2 Advanced Application Template:
+
+```php 
+<?php
+defined('YII_DEBUG') or define('YII_DEBUG', true);
+defined('YII_ENV') or define('YII_ENV', 'dev');
+
+require(__DIR__ . '/../../vendor/autoload.php');
+require(__DIR__ . '/../../vendor/yiisoft/yii2/Yii.php');
+require(__DIR__ . '/../../common/config/bootstrap.php');
+require(__DIR__ . '/../config/bootstrap.php');
+
+require(__DIR__ . '/../config/events.php'); // <--- adding events here! :)
+
+$config = yii\helpers\ArrayHelper::merge(
+    require(__DIR__ . '/../../common/config/main.php'),
+    require(__DIR__ . '/../../common/config/main-local.php'),
+    require(__DIR__ . '/../config/main.php'),
+    require(__DIR__ . '/../config/main-local.php')
+);
+
+$application = new yii\web\Application($config);
+$application->run();
+
+```
+
+© [2amigos](http://www.2amigos.us/) 2013-2017
diff --git a/src/User/Controller/AdminController.php b/src/User/Controller/AdminController.php
index 00ab267..f0ddf23 100644
--- a/src/User/Controller/AdminController.php
+++ b/src/User/Controller/AdminController.php
@@ -140,7 +140,7 @@ class AdminController extends Controller
                 $this->trigger(UserEvent::EVENT_AFTER_CREATE, $event);
                 return $this->redirect(['update', 'id' => $user->id]);
             } else {
-                Yii::$app->session->setFlash( 'danger', Yii::t('usuario', 'User account could not be created.'));
+                Yii::$app->session->setFlash('danger', Yii::t('usuario', 'User account could not be created.'));
             }
         }