minor fixes and user events docs

docs/events/user-events.md

@@ -0,0 +1,116 @@
+User Events
+===========
+
+The following is the list of the user events and where they happen: 
+
+On Controllers
+--------------
+
+- **AdminController**
+    - **UserEvent::EVENT_BEFORE_CREATE**: Occurs before a user has been created
+    - **UserEvent::EVENT_AFTER_CREATE**: Occurs after a user has been created 
+    - **UserEvent::EVENT_BEFORE_PROFILE_UPDATE**: Occurs before a user's profile has been updated
+    - **UserEvent::EVENT_AFTER_PROFILE_UPDATE**: Occurs after a user's profile has been updated
+    - **UserEvent::EVENT_BEFORE_CONFIRMATION**: Occurs before a user's email has been confirmed
+    - **UserEvent::EVENT_AFTER_CONFIRMATION**: Occurs after a user's email has been confirmed
+    - **UserEvent::EVENT_BEFORE_BLOCK**: Occurs before a user is being blocked (forbid access to app)
+    - **UserEvent::EVENT_AFTER_BLOCK**: Occurs after a user is being blocked (forbid access to app)
+    - **UserEvent::EVENT_BEFORE_UNBLOCK**: Occurs before a user is being un-blocked
+    - **UserEvent::EVENT_AFTER_UNBLOCK**: Occurs after a user is being un-blocked
+
+- **RegistrationController**
+    - **UserEvent::EVENT_BEFORE_REGISTER**: Occurs before user registration
+    - **UserEvent::EVENT_AFTER_REGISTER**: Occurs after user registration
+    - **UserEvent::EVENT_BEFORE_CONFIRMATION**
+    - **UserEvent::EVENT_AFTER_CONFIRMATION**
+
+- **SecurityController**
+    - **UserEvent::EVENT_BEFORE_LOGOUT**: Occurs before user logs out of the app
+    - **UserEvent::EVENT_AFTER_LOGOUT**: Occurs after user logs out of the app
+
+- **SettingsController**
+    - **UserEvent::EVENT_BEFORE_PROFILE_UPDATE**
+    - **UserEvent::EVENT_AFTER_PROFILE_UPDATE**
+    - **UserEvent::EVENT_BEFORE_ACCOUNT_UPDATE**: Occurs before the user account is updated
+    - **UserEvent::EVENT_AFTER_ACCOUNT_UPDATE**: Occurs after the user account is updated
+    - **UserEvent::EVENT_BEFORE_DELETE**: Occurs before the user account is deleted
+    - **UserEvent::EVENT_AFTER_DELETE**: Occurs after the user account is deleted
+
+On Models
+---------
+
+- **User**
+    - **UserEvent::EVENT_BEFORE_REGISTER**
+    - **UserEvent::EVENT_AFTER_REGISTER**
+    - **UserEvent::EVENT_BEFORE_CONFIRMATION**
+    - **UserEvent::EVENT_AFTER_CONFIRMATION**
+    - **UserEvent::EVENT_BEFORE_BLOCK**
+    - **UserEvent::EVENT_AFTER_BLOCK**
+    - **UserEvent::EVENT_BEFORE_UNBLOCK**
+    - **UserEvent::EVENT_AFTER_UNBLOCK**
+
+How to Work With User Events
+----------------------------
+
+All these events receive an instance of `Da\User\Event\UserEvent`. The Event receives an instance of a `Da\Model\User` 
+class 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 `AdminController` and the `User` model: 
+
+```php 
+<?php 
+// events.php file
+
+use Da\Controller\AdminController;
+use Da\Model\User;
+use yii\base\Event;
+
+// This will happen at the controller's level
+Event::on(AdminController::class, UserEvent::EVENT_BEFORE_CREATE, function (UserEvent $event) {
+    $user = $event->getUser();
+
+    // ... your logic here
+}
+
+// This will happen at the model's level
+Event::on(User::class, UserEvent::EVENT_BEFORE_CREATE, function (UserEvent $event) {
+
+    $user = $event->getUser();
+
+    // ... your logic here
+}
+
+```
+
+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

docs/index.md

@@ -124,6 +124,22 @@ Enhancing and Overriding
 - [Overriding Classes](enhancing-and-overriding/overriding-classes.md) 
 - [Overriding Views](enhancing-and-overriding/overriding-views.md)
 
+Events
+------
+
+Events are a good way to execute logic before and after certain processes. Yii2 Usuario comes with a huge list of them. 
+
+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). 
+
+- [User Events](events/user-events.md)
+- [Form Events](events/form-events.md)
+- [Reset Password Events](events/reset-password-events.md)
+- [Social Network Authentication Events](events/social-network-auth-events.md)
+- [Social Network Connection Events](events/social-network-connect-events.md)
+
+
 Helpful Guides
 --------------
 

src/User/Controller/AdminController.php

@@ -281,6 +281,7 @@ public function actionBlock($id)
                 Yii::$app->getSession()->setFlash('success', Yii::t('usuario', 'User block status has been updated.'));
             } else {
                 Yii::$app->getSession()->setFlash('danger', Yii::t('usuario', 'Unable to update block status.'));
+
             }
         }
 

src/User/Controller/RegistrationController.php

@@ -106,13 +106,15 @@ public function actionRegister()
             $mailService = MailFactory::makeWelcomeMailerService($user);
 
             if ($this->make(UserRegisterService::class, [$user, $mailService])->run()) {
+
                 Yii::$app->session->setFlash(
                     'info',
                     Yii::t(
                         'usuario',
                         'Your account has been created and a message with further instructions has been sent to your email'
                     )
                 );
+                $this->trigger(UserEvent::EVENT_AFTER_REGISTER, $event);
 
                 return $this->render(
                     '/shared/message',
@@ -175,6 +177,7 @@ public function actionConnect($code)
 
     public function actionConfirm($id, $code)
     {
+        /** @var User $user */
         $user = $this->userQuery->whereId($id)->one();
 
         if ($user === null || $this->module->enableEmailConfirmation === false) {

src/User/Controller/SettingsController.php

@@ -137,7 +137,7 @@ public function actionAccount()
     {
         /** @var SettingsForm $form */
         $form = $this->make(SettingsForm::class);
-        $event = $this->make(FormEvent::class, [$form]);
+        $event = $this->make(UserEvent::class, [$form->getUser()]);
 
         $this->make(AjaxRequestModelValidator::class, [$form])->validate();
 

src/User/Form/SettingsForm.php

@@ -121,12 +121,13 @@ public function getUser()
     public function save()
     {
         if ($this->validate()) {
-            $this->user->scenario = 'settings';
-            $this->user->username = $this->username;
-            $this->user->password = $this->new_password;
-            if ($this->email == $this->user->email && $this->user->unconfirmed_email != null) {
-                $this->user->unconfirmed_email = null;
-            } elseif ($this->email != $this->user->email) {
+            $user = $this->getUser();
+            $user->scenario = 'settings';
+            $user->username = $this->username;
+            $user->password = $this->new_password;
+            if ($this->email == $user->email && $user->unconfirmed_email != null) {
+                $user->unconfirmed_email = null;
+            } elseif ($this->email != $user->email) {
                 $strategy = EmailChangeStrategyFactory::makeByStrategyType(
                     $this->getModule()->emailChangeStrategy,
                     $this
@@ -135,7 +136,7 @@ public function save()
                 return $strategy->run();
             }
 
-            return $this->user->save();
+            return $user->save();
         }
 
         return false;

src/User/Service/UserBlockService.php

@@ -39,17 +39,23 @@ public function __construct(
     public function run()
     {
         if ($this->model->getIsBlocked()) {
-            $this->controller->trigger(UserEvent::EVENT_BEFORE_UNBLOCK, $this->event);
+            $this->triggerEvents(UserEvent::EVENT_BEFORE_UNBLOCK);
             $result = (bool)$this->model->updateAttributes(['blocked_at' => null]);
-            $this->controller->trigger(UserEvent::EVENT_AFTER_UNBLOCK, $this->event);
+            $this->triggerEvents(UserEvent::EVENT_AFTER_UNBLOCK);
         } else {
-            $this->controller->trigger(UserEvent::EVENT_BEFORE_BLOCK, $this->event);
+            $this->triggerEvents(UserEvent::EVENT_BEFORE_BLOCK);
             $result = (bool)$this->model->updateAttributes(
                 ['blocked_at' => time(), 'auth_key' => $this->securityHelper->generateRandomString()]
             );
-            $this->controller->trigger(UserEvent::EVENT_AFTER_BLOCK, $this->event);
+            $this->triggerEvents(UserEvent::EVENT_AFTER_BLOCK);
         }
 
         return $result;
     }
+
+    protected function triggerEvents($name)
+    {
+        $this->controller->trigger($name, $this->event);
+        $this->model->trigger($name, $this->event);
+    }
 }