diff --git a/README.md b/README.md index 87b82c9..ba53335 100644 --- a/README.md +++ b/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. diff --git a/docs/enhancing-and-overriding/overriding-controllers.md b/docs/enhancing-and-overriding/overriding-controllers.md new file mode 100644 index 0000000..031d5ad --- /dev/null +++ b/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 + + diff --git a/docs/enhancing-and-overriding/overriding-views.md b/docs/enhancing-and-overriding/overriding-views.md index d32f020..033c096 100644 --- a/docs/enhancing-and-overriding/overriding-views.md +++ b/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 diff --git a/docs/events/controller-events.md b/docs/events/controller-events.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/events/form-events.md b/docs/events/form-events.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/events/model-events.md b/docs/events/model-events.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.md b/docs/index.md index c13a564..8332021 100644 --- a/docs/index.md +++ b/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 ------------------------ diff --git a/docs/installation/advanced-application-template.md b/docs/installation/advanced-application-template.md index 23367b4..fc70140 100644 --- a/docs/installation/advanced-application-template.md +++ b/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 diff --git a/docs/installation/configuration-options.md b/docs/installation/configuration-options.md new file mode 100644 index 0000000..abe4993 --- /dev/null +++ b/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 +[ + '' => 'profile/show', + '' => 'security/', + '' => 'registration/', + 'confirm//' => 'registration/confirm', + 'forgot' => 'recovery/request', + 'recover//' => 'recovery/reset', + 'settings/' => 'settings/', +] +``` + +#### 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 diff --git a/src/User/Controller/RegistrationController.php b/src/User/Controller/RegistrationController.php index 966b239..c2db7f9 100644 --- a/src/User/Controller/RegistrationController.php +++ b/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); diff --git a/src/User/Module.php b/src/User/Module.php index a0e4a24..853e83a 100644 --- a/src/User/Module.php +++ b/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 longer it takes to generate the hash and to verify a password against it. Higher cost - * therefore slows down a brute-force attack. For best protection 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 $cost + * 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 best protection 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 $cost */ public $blowfishCost = 10; /**