From 10187e07740b9fd5693ef54da6f725b95894d39f Mon Sep 17 00:00:00 2001 From: Dmitry Erofeev Date: Mon, 6 Apr 2015 11:41:59 +0300 Subject: [PATCH] updated documentation #335 #297 --- README.md | 17 +++-- UPGRADE.md | 28 +++++--- docs/README.md | 2 + docs/adding-captcha.md | 13 ++-- docs/available-actions.md | 42 ++++++----- docs/getting-started.md | 7 ++ docs/mailer.md | 6 +- docs/overriding-controllers.md | 9 +-- docs/overriding-models.md | 6 +- docs/overriding-views.md | 6 +- docs/social-auth.md | 12 ++-- docs/usage-with-advanced-template.md | 100 +++++++++++++++++++++++++++ docs/user-management.md | 18 ++--- docs/yii2-rbac.md | 14 ++++ filters/BackendFilter.php | 38 ++++++++++ filters/FrontendFilter.php | 38 ++++++++++ 16 files changed, 275 insertions(+), 81 deletions(-) create mode 100644 docs/usage-with-advanced-template.md create mode 100644 docs/yii2-rbac.md create mode 100644 filters/BackendFilter.php create mode 100644 filters/FrontendFilter.php diff --git a/README.md b/README.md index e143a72ae..7eb0e106e 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # Yii2-user [![Build Status](https://img.shields.io/travis/dektrium/yii2-user/master.svg?style=flat-square)](https://travis-ci.org/dektrium/yii2-user) [![Packagist Version](https://img.shields.io/packagist/v/dektrium/yii2-user.svg?style=flat-square)](https://packagist.org/packages/dektrium/yii2-user) [![Total Downloads](https://img.shields.io/packagist/dt/dektrium/yii2-user.svg?style=flat-square)](https://packagist.org/packages/dektrium/yii2-user) [![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md) -Most of web applications provide a way for users to register, log in or reset their forgotten passwords. Rather than -re-implementing this on each application, you can use Yii2-user which is a flexible user management module for Yii2 that -handles common tasks such as registration, authentication and password retrieval. Current version includes following features: +Most of web applications provide a way for users to register, log in or reset +their forgotten passwords. Rather than re-implementing this on each application, +you can use Yii2-user which is a flexible user management module for Yii2 that +handles common tasks such as registration, authentication and password retrieval. +The latest version includes following features: * Registration with an optional confirmation per mail * Registration via social networks -* Password retrieval +* Password recovery * Account and profile management * Console commands * User management interface @@ -22,10 +24,7 @@ handles common tasks such as registration, authentication and password retrieval Anyone and everyone is welcome to contribute. Please take a moment to review the [guidelines for contributing](CONTRIBUTING.md). -* [Bug reports](CONTRIBUTING.md#bugs) -* [Feature requests](CONTRIBUTING.md#features) -* [Pull requests](CONTRIBUTING.md#pull-requests) - ## License -Yii2-user is released under the MIT License. See the bundled [LICENSE.md](LICENSE.md) for details. +Yii2-user is released under the MIT License. See the bundled [LICENSE.md](LICENSE.md) +for details. diff --git a/UPGRADE.md b/UPGRADE.md index dac1a02ed..e117bb7d7 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,16 +1,25 @@ Upgrading instructions for Yii2-user ==================================== -The following upgrading instructions are cumulative. That is, if you want to upgrade from version A to version C and -there is version B between A and C, you need to following the instructions for both A and B. +The following upgrading instructions are cumulative. That is, if you want to +upgrade from version A to version C and there is version B between A and C, you +need to following the instructions for both A and B. + +Upgrade from Yii2-user 0.9.* to Yii2-user 0.9.4 + +- New authentication via social networks has been introduced. You should update +your `authClientCollection` component as described in [guide](docs/social-auth.md). + +- Admin views have been remade. If you override admin view files, you should +update them accordingly to the made changes. Upgrade from Yii2-user 0.8.* ---------------------------- - **APPLY NEW MIGRATIONS!** -- `webUserClass` module option has been removed. If you use your own user component class you should set in `user` -application component configuration: +- `webUserClass` module option has been removed. If you use your own user +component class you should set in `user` application component configuration: ```php 'components' => [ @@ -20,8 +29,8 @@ application component configuration: ], ``` -- ModelManager component has been removed. If you override models, now you should set them via `modelMap` module's -property. +- ModelManager component has been removed. If you override models, now you +should set them via `modelMap` module's property. **Before:** @@ -55,8 +64,8 @@ property. ], ``` -- Mailer component has been changed. Now it should be configured via `mailer` module property. You can read more about -mailer configuration [here](docs/mailer.md). +- Mailer component has been changed. Now it should be configured via `mailer` +module property. You can read more about mailer configuration [here](docs/mailer.md). **Before:** @@ -86,4 +95,5 @@ mailer configuration [here](docs/mailer.md). ], ``` -- Urls `user/settings/email` and `user/settings/password` have been merged into a new one `user/settings/account`. \ No newline at end of file +- Urls `user/settings/email` and `user/settings/password` have been merged into +a new one `user/settings/account`. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index a122876c2..897f82abd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,7 @@ Yii2-user documentation is licensed under the [CC BY 4.0](http://creativecommons - [Configuration](configuration.md) - [List of available actions](available-actions.md) - [Troubleshooting](troubleshooting.md) +- [Usage with Yii2 advanced template](usage-with-advanced-template.md) ## Overriding @@ -25,6 +26,7 @@ Yii2-user documentation is licensed under the [CC BY 4.0](http://creativecommons ## RBAC +- [Powerful RBAC with Yii2-rbac](yii2-rbac.md) - [Simpler RBAC with access control filter](custom-access-control.md) ## Guides diff --git a/docs/adding-captcha.md b/docs/adding-captcha.md index 06ef2a932..3efac89f6 100644 --- a/docs/adding-captcha.md +++ b/docs/adding-captcha.md @@ -1,5 +1,4 @@ -How to add captcha to form -========================== +# How to add captcha to form Adding captcha to forms is pretty easy and can be done in three steps: @@ -10,9 +9,7 @@ Adding captcha to forms is pretty easy and can be done in three steps: In this guide I would like to show you how to add captcha field in the registration form but you can add captcha to any form following this steps. -1. Adding field and validation rules to model ---------------------------------------------- - +## 1. Adding field and validation rules to model First of all you need to override Registration form as described in special guide. After this done you have to add public property named **captcha** and validation rules. @@ -44,8 +41,7 @@ public property named **captcha** and validation rules. ``` -2. Adding widget to the view ----------------------------- +## 2. Adding widget to the view Before doing this step you have to configure view application component as described in guide. After this done you have to create new file named `register.php` in `@app/views/user/registration`. Now you have to add widget to registration @@ -102,8 +98,7 @@ form, just copy and paste following code into newly created view file. ``` -3. Adding action to the controller ----------------------------------- +## 3. Adding action to the controller In order to make captcha work you have to add captcha action to `app\controllers\SiteController` Maybe it is already added because standard Yii2 application template adds it automatically. diff --git a/docs/available-actions.md b/docs/available-actions.md index 181eaac1e..fd74579d9 100644 --- a/docs/available-actions.md +++ b/docs/available-actions.md @@ -1,21 +1,31 @@ -List of available actions -========================= +# List of available actions Yii2-user includes a lot of actions, which you can access by creating URLs for them. Here is the table of available actions which contains route and short description of each action. You can create URLs for them using special Yii helper `\yii\helpers\Url::to()`. -|Route |Description | -|-------------------------------|-----------------------------------------------------------------------| -|**/user/registration/register**| Displays registration form | -|**/user/registration/resend** | Displays resend form | -|**/user/registration/confirm** | Confirms a user (requires *id* and *token* query params) | -|**/user/security/login** | Displays login form | -|**/user/security/logout** | Logs the user out (available only via POST method) | -|**/user/recovery/request** | Displays recovery request form | -|**/user/recovery/reset** | Displays password reset form (requires *id* and *token* query params) | -|**/user/settings/profile** | Displays profile settings form | -|**/user/settings/account** | Displays account settings form (email, username, password) | -|**/user/settings/networks** | Displays social network accounts settings page | -|**/user/profile/show** | Displays user's profile (requires *id* query param) | -|**/user/admin/index** | Displays user management interface | +- **/user/registration/register** Displays registration form +- **/user/registration/resend** Displays resend form +- **/user/registration/confirm** Confirms a user (requires *id* and *token* query params) +- **/user/security/login** Displays login form +- **/user/security/logout** Logs the user out (available only via POST method) +- **/user/recovery/request** Displays recovery request form +- **/user/recovery/reset** Displays password reset form (requires *id* and *token* query params) +- **/user/settings/profile** Displays profile settings form +- **/user/settings/account** Displays account settings form (email, username, password) +- **/user/settings/networks** Displays social network accounts settings page +- **/user/profile/show** Displays user's profile (requires *id* query param) +- **/user/admin/index** Displays user management interface + +## Example of menu + +You can add links to registration, login and logout as follows: + +```php +Yii::$app->user->isGuest ? + ['label' => 'Sign in', 'url' => ['/user/security/login']] : + ['label' => 'Sign out (' . Yii::$app->user->identity->username . ')', + 'url' => ['/user/security/logout'], + 'linkOptions' => ['data-method' => 'post']], +['label' => 'Register', 'url' => ['/user/registration/register'], 'visible' => Yii::$app->user->isGuest] +``` \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md index a7071c44d..517d60b7b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,6 +4,8 @@ Yii2-user is designed to work out of the box. It means that installation require minimal steps. Only one configuration step should be taken and you are ready to have user management on your Yii2 website. +> If you're using Yii2 advanced template, you should read [this article](usage-with-advanced-template.md) firstly. + ### 1. Download Yii2-user can be installed using composer. Run following command to download and @@ -37,6 +39,11 @@ and run the following command: $ php yii migrate/up --migrationPath=@vendor/dektrium/yii2-user/migrations ``` +## Where do I go now? + +You have Yii2-user installed. Not you can check out the [list of articles](README.md) +for more information. + ## Troubleshooting If you're having troubles with Yii2-user, make sure to check out the diff --git a/docs/mailer.md b/docs/mailer.md index a32463bf6..40802343c 100644 --- a/docs/mailer.md +++ b/docs/mailer.md @@ -1,5 +1,4 @@ -Mailer -====== +# Mailer Yii2-user includes special component named Mailer, which is used to send emails in four different instances: @@ -8,8 +7,7 @@ Yii2-user includes special component named Mailer, which is used to send emails - Email change confirmation message - Recovery message -Configuration -------------- +## Configuration Mailer can be configured as followed: diff --git a/docs/overriding-controllers.md b/docs/overriding-controllers.md index f897f0586..297e48049 100644 --- a/docs/overriding-controllers.md +++ b/docs/overriding-controllers.md @@ -1,11 +1,9 @@ -Overriding controllers -====================== +# Overriding controllers The default Yii2-user controllers provide a lot of functionality that is sufficient for general use cases. But sometimes you may need to extend that functionality and add some logic that suits your needs. -Step 1: Create new controller ------------------------------ +## Step 1: Create new controller First of all you should create new controller under your own namespace (it is recommended to use `app\controllers\user`) and extend it from the controller you want to override. @@ -27,8 +25,7 @@ class AdminController extends BaseAdminController } ``` -Step 2: Add your controller to controller map ---------------------------------------------- +## Step 2: Add your controller to controller map To let Yii2-user know about your controller, you should add it to the module's controller map, as follows: diff --git a/docs/overriding-models.md b/docs/overriding-models.md index ce879ecab..480bacc19 100644 --- a/docs/overriding-models.md +++ b/docs/overriding-models.md @@ -1,5 +1,4 @@ -Overriding models -================= +# Overriding models When you are creating application with Yii2-user you can find that you need to override models or forms. This guide describes how you can override any model used by Yii2-user. Moreover you can attach any behavior or event handler to any @@ -34,8 +33,7 @@ In order to make Yii2-user use your class you need to configure module as follow ... ``` -Attaching behaviors and event handlers --------------------------------------- +## Attaching behaviors and event handlers Yii2-user allows you to attach behavior or event handler to any model. To do this you can set model map like so: diff --git a/docs/overriding-views.md b/docs/overriding-views.md index 2618db70a..628cbc549 100644 --- a/docs/overriding-views.md +++ b/docs/overriding-views.md @@ -1,5 +1,4 @@ -Overriding views -================ +# Overriding views When you start using Yii2-user you will probably find that you need to override the default views provided by the module. Although view names are not configurable, Yii2 provides a way to override views using themes. To get started you should @@ -22,8 +21,7 @@ configure your view application component as follows: In the above `pathMap` means that every view in @dektrium/user/views will be first searched under `@app/views/user` and if a view exists in the theme directory it will be used instead of the original view. -Example -------- +## Example An example of overriding the registration page view is demonstrated below. First make sure you have configured view application component. diff --git a/docs/social-auth.md b/docs/social-auth.md index dca2b198c..32215aed1 100644 --- a/docs/social-auth.md +++ b/docs/social-auth.md @@ -1,12 +1,10 @@ -Authentication via social networks -================================== +# Authentication via social networks Yii2-user provides user registration and login using social sites credentials. It also allows to connect multiple social networks to user account and use them to log in. -Getting started ---------------- +## Getting started To get started you should configure `authClientCollection` application component: @@ -26,8 +24,7 @@ To get started you should configure `authClientCollection` application component ... ``` -Available clients ------------------ +## Available clients Here is the list of clients supported by the module: @@ -118,8 +115,7 @@ Here is the list of clients supported by the module: ], ``` -Configuration example ---------------------- +## Configuration example The following config allows to log in using 3 networks (Twitter, Facebook and Google): diff --git a/docs/usage-with-advanced-template.md b/docs/usage-with-advanced-template.md new file mode 100644 index 000000000..7d64ae9f2 --- /dev/null +++ b/docs/usage-with-advanced-template.md @@ -0,0 +1,100 @@ +# Yii2-user with Yii2 advanced template + +When using advanced template, you may want to have AdminController only available +in backend, and all other controllers available in frontend. This guide will +help you with implementing this. + +## Install + +Install module as described in [getting started](getting-started.md) guide, without +configuring module as described in step 2. + +## Configure application + +Let's start with defining module in `@common/config/main.php`: + +```php +'modules' => [ + 'user' => [ + 'class' => 'dektrium\user\Module', + // you will configure your module inside this file + // or if need different configuration for frontend and backend you may + // configure in needed configs + ], +], +``` + +Now we should restrict access to admin controller in frontend application. Open +`@frontend/config/main.php` and add following: + +``` +'modules' => [ + 'user' => [ + // following line will restrict access to admin page + 'as frontend' => 'dektrium\user\filters\FrontendFilter', + ], +], +``` + +Also do the same thing with `@backend/config/main.php`: + +``` +'modules' => [ + 'user' => [ + // following line will restrict access to admin page + 'as backend' => 'dektrium\user\filters\BackendFilter', + ], +], +``` + +That's all, now you have module installed and configured in advanced template. + +## Use independent sessions in one domain + +If you have frontend and backend apps in one domain (e.g. domain.com and domain.com/admin), +sometimes you may need to have independent sessions for them, which means that +if you log in on frontend, you will not be logged in on backend. + +Configure `@backend\config\main.php`: + +```php +'components' => [ + 'user' => [ + 'identityCookie' => [ + 'name' => '_backendIdentity', + 'path' => '/admin', + 'httpOnly' => true, + ], + ], + 'session' => [ + 'name' => 'BACKENDSESSID', + 'cookieParams' => [ + 'httpOnly' => true, + 'path' => '/admin', + ], + ], +], +``` + +Then configure `@frontend\config\main.php`: + +```php +'components' => [ + 'user' => [ + 'identityCookie' => [ + 'name' => '_frontendIdentity', + 'path' => '/', + 'httpOnly' => true, + ], + ], + 'session' => [ + 'name' => 'FRONTENDSESSID', + 'cookieParams' => [ + 'httpOnly' => true, + 'path' => '/', + ], + ], +], +``` + +From now you have two different sessions for frontend and backend. \ No newline at end of file diff --git a/docs/user-management.md b/docs/user-management.md index 1fdb1b748..6a762eab4 100644 --- a/docs/user-management.md +++ b/docs/user-management.md @@ -1,5 +1,4 @@ -User management -=============== +# User management When you start using Yii2-user you will probably find that you need to create, update and delete accounts of other users. In order to do that Yii2-user provides CRUD interface. @@ -20,34 +19,29 @@ To start using user management interface you have to add your username to admini ... ``` -Show users ----------- +### Show users Route **/user/admin/index** shows a list of registered users. You will be able to see a lot of useful information such as registration time and ip address, confirmation and block status, etc. -Create user ------------ +### Create user Route **/user/admin/create** shows create user form. To create a new user account you have to fill username and email fields. If you do not want to create password for user leave password field empty, password will be generated automatically. After create a welcome message will be sent to email that you have used to create user. It will contain user's credentials. -Update user ------------ +### Update user Route **/user/admin/update** shows update user form. From that page you will be able to update account (email, username, password) and profile (name, location, etc) information, block and confirm user. To access this route you should specify id query parameter. -Delete user ------------ +### Delete user Route **/user/admin/delete** deletes an user account. To access this route you should specify id query parameter and do a POST request. Be careful, you will not be able to restore deleted account. -Changing CRUD layout -==================== +##Changing CRUD layout Sometimes you will need to have different layouts for frontend and backend pages. It is really easy to change admin layout: diff --git a/docs/yii2-rbac.md b/docs/yii2-rbac.md new file mode 100644 index 000000000..0db5c5a40 --- /dev/null +++ b/docs/yii2-rbac.md @@ -0,0 +1,14 @@ +# Powerful RBAC with Yii2-rbac + +Yii2-rbac is another extension for Yii2 which provides CRUD operations for RBAC +and also is highly integrated with Yii2-user and allows to assign roles and +permissions to users. + +## Installation + +Installation instructions are located in [Yii2-rbac repository](https://github.com/dektrium/yii2-rbac). + +## Usage + +After installing Yii2-rbac you will be able to manage auth items (roles and +permissions) and assign them to users on update page. diff --git a/filters/BackendFilter.php b/filters/BackendFilter.php new file mode 100644 index 000000000..702067372 --- /dev/null +++ b/filters/BackendFilter.php @@ -0,0 +1,38 @@ + + * + * For the full copyright and license information, please view the LICENSE.md + * file that was distributed with this source code. + */ + +namespace dektrium\user\filters; + +/** + * BackendFilter is used to allow access only to admin controller in frontend + * when using Yii2-user with Yii2 advanced template. + * + * @author Dmitry Erofeev + */ +class BackendFilter extends \yii\base\ActionFilter +{ + /** + * @var array + */ + public $controllers = ['profile', 'recovery', 'registration', 'security', 'settings']; + + /** + * @param \yii\base\Action $action + */ + public function beforeAction($action) + { + if (in_array($action->controller->id, $this->controllers)) { + throw new \yii\web\NotFoundHttpException('Not found'); + } + + return true; + } +} \ No newline at end of file diff --git a/filters/FrontendFilter.php b/filters/FrontendFilter.php new file mode 100644 index 000000000..38dc153e2 --- /dev/null +++ b/filters/FrontendFilter.php @@ -0,0 +1,38 @@ + + * + * For the full copyright and license information, please view the LICENSE.md + * file that was distributed with this source code. + */ + +namespace dektrium\user\filters; + +/** + * FrontendFilter is used to restrict access to admin controller in frontend + * when using Yii2-user with Yii2 advanced template. + * + * @author Dmitry Erofeev + */ +class FrontendFilter extends \yii\base\ActionFilter +{ + /** + * @var array + */ + public $controllers = ['admin']; + + /** + * @param \yii\base\Action $action + */ + public function beforeAction($action) + { + if (in_array($action->controller->id, $this->controllers)) { + throw new \yii\web\NotFoundHttpException('Not found'); + } + + return true; + } +} \ No newline at end of file