update docs

README.md

@@ -1,14 +1,13 @@
 Yii2 Usuario Extension
 ======================
 
-[![Build Status](https://travis-ci.org/2amigos/yii2-usuario.svg?branch=master)](https://travis-ci.org/2amigos/yii2-usuario)
 [![Documentation Status](https://readthedocs.org/projects/yii2-usuario/badge/?version=latest)](http://yii2-usuario.readthedocs.io/en/latest/?badge=latest)
-[![Join the chat at https://gitter.im/2amigos/yii2-usuario](https://badges.gitter.im/2amigos/yii2-usuario.svg)](https://gitter.im/2amigos/yii2-usuario?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)  
+[![Join the chat at https://gitter.im/2amigos/yii2-usuario](https://badges.gitter.im/2amigos/yii2-usuario.svg)](https://gitter.im/2amigos/yii2-usuario?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Packagist Version](https://img.shields.io/packagist/v/2amigos/yii2-usuario.svg?style=flat-square)](https://packagist.org/packages/2amigos/yii2-usuario)
 [![Latest Stable Version](https://poser.pugx.org/2amigos/yii2-usuario/version)](https://packagist.org/packages/2amigos/yii2-usuario)
 [![Total Downloads](https://poser.pugx.org/2amigos/yii2-usuario/downloads)](https://packagist.org/packages/2amigos/yii2-usuario)
 [![Latest Unstable Version](https://poser.pugx.org/2amigos/yii2-usuario/v/unstable)](//packagist.org/packages/2amigos/yii2-usuario)  
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/2amigos/yii2-usuario/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/2amigos/yii2-usuario/?branch=master)
-[![Code Coverage](https://scrutinizer-ci.com/g/2amigos/yii2-usuario/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/2amigos/yii2-usuario/?branch=master)
 
 Yii 2 usuario is a highly customizable and extensible user management, RBAC management, authentication, 
 and authorization Yii2 module extension. 

docs/enhancing-and-overriding/overriding-controllers.md

@@ -0,0 +1,48 @@
+Overriding Controllers
+======================
+
+Maybe you need to override the default's functionality of the module's controllers. For that, as you probably know, 
+Yii2 Modules have an attribute named `controllerMap` that you can configure with your very own controllers.
+
+Please, before you override a controller's action, make sure that it won't be enough with using the 
+(controller's events)[../events/controller-events.md].
+
+> See more about this attribute on 
+> [ The Definitive Guide to Yii 2.0](http://www.yiiframework.com/doc-2.0/guide-structure-controllers.html#controller-map) 
+
+How to Override
+---------------
+
+First, create your new controller: 
+
+```php 
+namespace app\controllers;
+
+use Da\User\Controller\RegistrationController as BaseController;
+
+class ProfileController extends BaseController {
+    
+    public function actionConfirm($id, $code) {
+        // ... your code here
+    }
+}
+
+```
+
+Now, the only thing that is missing is to add your brand new controller to the module's controller's map: 
+
+```php 
+'modules' => [
+    // ...
+    'user' => [
+        'class' => 'Da\User\Module',
+        'controllerMap' => [
+            'profile' => 'app\controllers\ProfileController'
+        ]
+    ]
+]
+```
+
+© [2amigos](http://www.2amigos.us/) 2013-2017
+
+

docs/enhancing-and-overriding/overriding-views.md

@@ -20,7 +20,7 @@ Bootstrap), Yii2 provides a mechanism that is really easy to do:
 
 The above code tells Yii2 to search on `@app/view/user` for views prior to go to `@Da/User/resources/views`. That is, 
 if a view is found on `@app/view/user` that matches the required render it will be displayed instead of the one on 
-`@Da/User/resources/views`. 
+`@Da/User/resources/views`.
 
 You need to remember that the folder structure on your new location must match that of the module. For example, if we 
 wish to override the `login.php` view using the above setting, we would have to create the following structure on our 
@@ -38,4 +38,17 @@ app  [ Your root ]
 See how it follows the same structure as within the User's module `resources/views` path? Well, that's what you should 
 do with any of the others in order to override them.
 
+There is another way, and is by setting the `viewPath` attribute of the module: 
+
+```php
+'modules' => [
+    'user' => [
+        'class' => Da\User\Module::class,
+        'viewPath' => '@app/views/user'
+    ],
+],
+```
+But it will force you to override **ALL** views from the module. The recommended way is throughout the `theme` property 
+of `view` component as previously mentioned.
+
 © [2amigos](http://www.2amigos.us/) 2013-2017

docs/index.md

@@ -1,13 +1,12 @@
 # Yii2 Usuario Extension
 
-[![Build Status](https://travis-ci.org/2amigos/yii2-usuario.svg?branch=master)](https://travis-ci.org/2amigos/yii2-usuario)
 [![Documentation Status](https://readthedocs.org/projects/yii2-usuario/badge/?version=latest)](http://yii2-usuario.readthedocs.io/en/latest/?badge=latest)
-[![Join the chat at https://gitter.im/2amigos/yii2-usuario](https://badges.gitter.im/2amigos/yii2-usuario.svg)](https://gitter.im/2amigos/yii2-usuario?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)  
+[![Join the chat at https://gitter.im/2amigos/yii2-usuario](https://badges.gitter.im/2amigos/yii2-usuario.svg)](https://gitter.im/2amigos/yii2-usuario?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Packagist Version](https://img.shields.io/packagist/v/2amigos/yii2-usuario.svg?style=flat-square)](https://packagist.org/packages/2amigos/yii2-usuario)
 [![Latest Stable Version](https://poser.pugx.org/2amigos/yii2-usuario/version)](https://packagist.org/packages/2amigos/yii2-usuario)
 [![Total Downloads](https://poser.pugx.org/2amigos/yii2-usuario/downloads)](https://packagist.org/packages/2amigos/yii2-usuario)
 [![Latest Unstable Version](https://poser.pugx.org/2amigos/yii2-usuario/v/unstable)](//packagist.org/packages/2amigos/yii2-usuario)  
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/2amigos/yii2-usuario/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/2amigos/yii2-usuario/?branch=master)
-[![Code Coverage](https://scrutinizer-ci.com/g/2amigos/yii2-usuario/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/2amigos/yii2-usuario/?branch=master)
 
 Yii 2 usuario is a highly customizable and extensible user management, RBAC management, authentication, 
 and authorization Yii2 module extension. 
@@ -110,6 +109,10 @@ the official Yii2 advanced application template:
 - [Sidekit Application Template](installation/sidekit-application-template.md)
 - [Advanced Application Template](installation/advanced-application-template.md)
 
+See also all the possible configuration options available: 
+
+- [Configuration Options](installation/configuration-options.md)
+
 Enhancing and Overriding
 ------------------------
 

docs/installation/advanced-application-template.md

@@ -42,23 +42,6 @@ return [
 ];
 ```
 
-Our extension implemented as some kind of substructure containing its own MVC entities, so another thing you have
-to register it as an application module by adding following lines to the same configuration script file:
-
-```php
-return [
-    // ...
-    'modules' => [
-        'user' => [
-            'class' => Da\User\Module::class,
-        ],
-    ],
-    'components' => [
-        // ...
-    ],
-];
-```
-
 That's all from the part of the web application.
 
 Step 3 - Apply database schema migrations

docs/installation/configuration-options.md

@@ -0,0 +1,126 @@
+Configuration Options
+=====================
+
+The module comes with a set of attributes to configure. The following is the list of all available options: 
+
+#### enableRegistration (type: `boolean`, default: `true`)
+
+Setting this attribute allows the registration process. If you set it to `false`, the module won't allow users to 
+register by throwing a `NotFoundHttpException` if the `RegistrationController::actionRegister()` is accessed. 
+
+#### enableEmailConfirmation (type: `boolean`, default: `true`)
+
+If `true`, the module will send an email with a confirmation link that user needs to click through to complete its 
+registration process.
+
+
+#### enableFlashMessages (type: `boolean`, default: `true`)
+
+If `true` views will display flash messages. 
+
+#### generatePasswords (type: `boolean`, default: `true`)
+
+If `true` the password field will be hidden on the registration page and passwords will be generated automatically and 
+sent to the user via email.
+
+#### allowUnconfirmedEmailLogin (type: `boolean`, default: `false`)
+
+If `true` it will allow users to login with unconfirmed emails.
+  
+#### allowPasswordRecovery (type: `boolean`, default: `true`)
+
+If `true` it will enable password recovery process.
+
+#### allowAccountDelete (type: `boolean`, default: `true`)
+
+If `true` users will be able to remove their own accounts. 
+
+#### emailChangeStrategy (type: `integer`, default: `MailChangeStrategyInterface::TYPE_DEFAULT`)
+
+Configures one of the three ways available to change user's password:
+
+- **MailChangeStrategyInterface::TYPE_DEFAULT**: A confirmation message will be sent to the new user's email with a link 
+    that needs to be click through to confirm  it.
+- **MailChangeStrategyInterface::TYPE_INSECURE**: Email will be changed without any confirmation message. 
+- **MailChangeStrategyInterface::TYPE_SECURE**: A confirmation message will be sent to the previous and new user's email 
+    with a link that would require both to be click through to confirm the change.
+    
+#### rememberLoginLifespan (type: `integer`, default: `209600`)
+
+Configures the time length in seconds a user will be remembered without the need to login again. The default time is 2 
+weeks. 
+
+#### tokenConfirmationLifespan (type: `integer`, default: `86400`)
+
+Configures the time length in seconds a confirmation token is valid. The default time is 24 hours.
+  
+#### tokenRecoveryLifespan (type: `integer`, default: `21600`)
+
+Configures the time length in seconds a recovery token is valid. The default time is 6 hours.
+
+#### administrators (type: `array`, default: `[]`)
+
+Configures the usernames of those users who are considered `admininistrators`. The administrators can be 
+configured here or throughout RBAC with a special permission name. The recommended way is throughout 
+`administratorPermissionName` as they can be set dynamically throughout the RBAC interface, but use this attribute for 
+simple backends with static administrators that won't change throughout time.   
+
+#### administratorPermissionName (type: `string`, default: `null`)
+
+Configures the permission name for `administrators`. See [AuthHelper](../../src/User/Helper/AuthHelper.php).
+ 
+#### prefix (type: `string`, default: `user`) 
+
+Configures the URL prefix for the module. 
+
+
+### mailParams (type: `array`, default: `[]`)
+
+Configures the parameter values used on [MailFactory](../../src/User/Factory/MailFactory.php). The default values are: 
+
+```php
+[
+    'fromEmail' => 'no-reply@example.com',
+    'welcomeMailSubject' => Yii::t('usuario', 'Welcome to {0}', $app->name),
+    'confirmationMailSubject' => Yii::t('usuario', 'Confirm account on {0}', $app->name),
+    'reconfirmationMailSubject' => Yii::t('usuario', 'Confirm email change on {0}', $app->name),
+    'recoveryMailSubject' => Yii::t('usuario', 'Complete password reset on {0}', $app->name),
+]
+```
+
+#### blowfishCost (type: `integer`, default: `10`)
+
+Is the cost parameter used by the Blowfish hash algorithm. The higher the value of cost, the longer it takes to generate 
+the hash and to verify a password against it. Higher cost therefore slows down a brute-force attack. For the best 
+protected against brute-force attacks, set it to the highest value that is tolerable on production servers. The time 
+taken to compute the hash doubles for every increment by one of `$blowfishCost`.
+
+
+#### classMap (type: `array`, default: `[]`)
+
+Configures the definitions of the classes as they have to be override. For more information see 
+[Overriding Classes](../enhancing-and-overriding/overriding-classes.md). 
+
+#### routes (type: `array`, default: `[]` )
+
+The routes (url rules) of the module for the URL management. The default values are: 
+
+```php 
+[
+    '<id:\d+>' => 'profile/show',
+    '<action:(login|logout)>' => 'security/<action>',
+    '<action:(register|resend)>' => 'registration/<action>',
+    'confirm/<id:\d+>/<code:[A-Za-z0-9_-]+>' => 'registration/confirm',
+    'forgot' => 'recovery/request',
+    'recover/<id:\d+>/<code:[A-Za-z0-9_-]+>' => 'recovery/reset',
+    'settings/<action:\w+>' => 'settings/<action>',
+]
+```
+
+#### viewPath (type: `string`, default: `@Da/User/resources/views`)
+
+Configures the root directory of the view files. See [overriding views](../enhancing-and-overriding/overriding-views.md).
+
+
+
+© [2amigos](http://www.2amigos.us/) 2013-2017

src/User/Controller/RegistrationController.php

@@ -100,7 +100,7 @@ class RegistrationController extends Controller
 
         if ($form->load(Yii::$app->request->post()) && $form->validate()) {
             $this->trigger(UserEvent::EVENT_BEFORE_REGISTER, $event);
-
+            /** @var User $user */
             $user = $this->make(User::class, [], $form->attributes);
             $user->setScenario('register');
             $mailService = MailFactory::makeWelcomeMailerService($user);

src/User/Module.php

@@ -81,11 +81,10 @@ class Module extends BaseModule
     public $mailParams = [];
     /**
      * @var int the cost parameter used by the Blowfish hash algorithm.
-     *          The higher the value of cost,
+     *          The higher the value of cost, the longer it takes to generate the hash and to verify a password
-     *          the longer it takes to generate the hash and to verify a password against it. Higher cost
+     *          against it. Higher cost therefore slows down a brute-force attack. For best protection against
-     *          therefore slows down a brute-force attack. For best protection against brute-force attacks,
+     *          brute-force attacks, set it to the highest value that is tolerable on production servers. The time taken
-     *          set it to the highest value that is tolerable on production servers. The time taken to
+     *          to compute the hash doubles for every increment by one of $cost
-     *          compute the hash doubles for every increment by one of $cost
      */
     public $blowfishCost = 10;
     /**