From 94b6de091d71915c70876d0f707d3c16c13d0f5c Mon Sep 17 00:00:00 2001 From: Razip Date: Sun, 9 Jul 2017 18:05:01 +0500 Subject: [PATCH] Corrections --- README.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index b486dee..c43f8d3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ hoauth v1.2.5 ============= -* `hoauth` extension provides simple integration with social network authorization lib [Hybridauth](http://hybridauth.sourceforge.net/) in Yii. (facebook, google, twitter, vkontakte and much more). +* `hoauth` extension provides a simple integration with social network authorization lib [Hybridauth](http://hybridauth.sourceforge.net/) in Yii. (facebook, google, twitter, vkontakte and much more). * Automatically finds and supports `yii-user` module ([instruction for yii-user](https://github.com/SleepWalker/hoauth/wiki/%5Binstall%5D-hoauth-and-yii-user-extension)). * supports prefixed tables * Supports I18N ([available translations](https://github.com/SleepWalker/hoauth/tree/master/messages)) @@ -29,29 +29,29 @@ Available social networks Additional social networks providers can be found at HybridAuth [website](http://hybridauth.sourceforge.net/download.html). And how to configure them [here](http://hybridauth.sourceforge.net/userguide.html) at the bottom of the page. -A little about how it's woks ----------------------------- +A little about how it works +--------------------------- The users of `yii-user` extension can skip this section, because `hoauth` will do all the stuff automatically. -This extension authenticates and if it's need creates new user. When user was registered "locally" (so he has login (email) and password), then he can also log in with it's social account (extension checks if user with provided email exists in db, when yes, the he will be logged in and it is no matter how had he registered earlier - locally or not). After the user logged in he will be redirected to `Yii::app()->user->returnUrl`. +This extension authenticates and if it's needed, creates a new user. When the user has been registered "locally" (so it has a login (email) and a password), then it can also log in with its social account (extension checks whether a user with the provided email exists in db, and if the user exists, it will be logged in and it is no matter how had he registered earlier - locally or not). After the user logged in, it will be redirected to `Yii::app()->user->returnUrl`. -This extension requires `UserIdentity` class, but doesn't use `authenticate()` method of `UserIdentity` class. Class constructor called with parameters `new UserIdentity($mail, null)` and than called `CWebUser::login()` method (while authentication work did for us social network). When social network didn't give us user's email, the **hoauth** will ask user for email, when email exists in our db, the password will be asked too. At the end we bind provided by social network unique user identifier to user id for future sign in. [Example of UserIdentity class](https://github.com/SleepWalker/hoauth/wiki/UserIdentity-class-example). +This extension requires `UserIdentity` class, but it doesn't use `authenticate()` method of `UserIdentity` class. The class' constructor is called with following parameters `new UserIdentity($mail, null)` and `CWebUser::login()` method is called then (while authentication work did for us social network). If social network doesn't give us the user's email, **hoauth** will ask the user for the email, and when the email exists in our db, the password will be asked too. At the end, we bind a unique user identifier that is provided by the social network to the user id for future's sign in. [Example of UserIdentity class](https://github.com/SleepWalker/hoauth/wiki/UserIdentity-class-example). -If you need to perform some access check for user, you can use `hoauthCheckAccess($user)` callback (simply create new method in controller where you added `HOAuthAction`). This method will be called with one input argument - *User model* of the user being authorized. This method should return integer values (`accessCode`) depending on the scenario needed: +If you need to perform some access checks for the user, you can use `hoauthCheckAccess($user)` callback (simply create new method in controller where you added `HOAuthAction`). This method will be called with one input argument - *User model* of the user being authorized. This method should return integer values (`accessCode`) depending on the scenario needed: * 0 - user shouldn't get access * 1 - user may login * 2 - user may login, but not now (e.g. the email should be verified and activated) You can also not only return the `accessCode`, but also render the page with error or any information you need. -**NOTE:** This extension will also automatically create `user_oauth` table in your database. About it see "`UserOAuth` model" section. +**NOTE:** This extension will automatically create `user_oauth` table in your database. See "`UserOAuth` model" section. Installation and Usage ---------------------- * [instruction for yii-user](https://github.com/SleepWalker/hoauth/wiki/%5Binstall%5D-hoauth-and-yii-user-extension) -**1\.** Make `hoauth` directory in your `extensions` directory (or in any other directory you want) and copy the content files there. -Directory structure example: +**1\.** Create a new directory called `hoauth` in your `extensions` directory (or any other directory you prefer) and copy the content files there. +A directory structure example: ```php /protected/ extesions/ @@ -127,21 +127,21 @@ class SiteController extends Controller } ``` -**4\.** Visit your `oauthadmin` action (eg. http://yoursite.com/site/oauthadmin) to create the HybridAuth config. For your `HybridAuth Endpoint URL` use this: http://yoursite.com/site/oauth. After install you can leave `install.php` in your file system, while it's in Yii protected directory. But you must **remove** `oauthadmin` action, or make such rules, that give access only for admin users. Config file can be found at `application.config.hoauth` +**4\.** Run your `oauthadmin` action (eg. visit http://yoursite.com/site/oauthadmin) to create the HybridAuth config. For your `HybridAuth Endpoint URL` use this: http://yoursite.com/site/oauth. After the installation, you can keep `install.php` in your file system, while it's in Yii protected directory. But you must **remove** `oauthadmin` action, or make such rules, that give access for admin users only. The config file can be found at `application.config.hoauth` **5\.** Add social login widget to your login page view (you can use `route` property, when you placing your widget not in the same module/controller as your `oauth` action): ```php widget('ext.hoauth.widgets.HOAuth'); ?> ``` -This widget can be switched to icon view using `onlyIcons` property. It may be also usefull the properties to adjust popup window size: `popupWidth` and `popupHeight`. See `HOAuth.php` file for details. +This widget can be switched to the icon view using `onlyIcons` property. It may also be useful for the properties to adjust popup window size: `popupWidth` and `popupHeight`. See `HOAuth.php` file for details. **Optional:** -**6\.** When you planning to use social networks like **Twitter**, that returns no email from user profile, you should declare `verifyPassword($password)` or `validatePassword($password)` method in `User` model, that should take the password (not hash) and return `true` if it is valid. -**7\.** You can also declare the `sendActivationMail()` method, that should mark the user account as inactive and send the mail for activation. This method, when it's exists will be used for social networks like **Twitter**, that give us no data about user's email (because we need to proof that user entered the right email). +**6\.** When you're planning to use social networks that return no email from the user profile (like **Twitter**), you should declare `verifyPassword($password)` or `validatePassword($password)` method in `User` model, that should take the password (not hash) and return `true` if it is valid. +**7\.** You can also declare the `sendActivationMail()` method, that should mark the user's account as inactive and send the mail for activation. This method, when it exists will be used for social networks like **Twitter**, that give us no information about the user's email (because we need to proof that the user has entered using the right email). Note ---- -If you want to correctly display the facebook popup, you should add `"display" => "popup"` to the Facebook configuration array in `protected/config/hoauth.php`. E.g.: +If you want to display the facebook popup correctly, you should add `"display" => "popup"` to the Facebook configuration's array in `protected/config/hoauth.php`. E.g.: ```php ... "Facebook" => array ( @@ -157,23 +157,23 @@ Available social profile fields ------------------------------- You can find them at HybridAuth [website](http://hybridauth.sourceforge.net/userguide/Profile_Data_User_Profile.html). -And here is some additional fields, that I needed in my project, you can use them too: +And here are some additional fields, that I personally needed in my project, but you can use them too: * `birthDate` - The full date of birthday (eg. 1991-09-03) * `genderShort` - short representation of gender (eg. 'm', 'f') Additional properties for `HOAuthAction` ---------------------------------------- -* `useYiiUser` - enables support for `yii-user` (default: false). `hoauth` will find `yii-user` module automatically, so you can leave this property as default. You may also leave `attributes` and `model` properties as default. -* `enabled` - defines whether the ouath functionality is active. Useful for example for CMS, where user can enable or disable oauth functionality in control panel. (default: true) +* `useYiiUser` - enables support for `yii-user` (default: false). `hoauth` will find `yii-user` module automatically, so you can keep this property as default. You may also keep `attributes` and `model` properties as default. +* `enabled` - defines whether the ouath functionality is active. For example, it is useful for CMS, where the user can enable or disable oauth functionality in the control panel. (default: true) * `scenario` - scenario name for the $model (optional) * `loginAction` - name of a local login action (should be in the same controller as `oauth` action). (default: 'actionLogin') * `duration` - 'remember me' duration in ms. (default: 2592000 //30days) -* `usernameAttribute` - you can specify username attribute, when it must be unique (like in `yii-user` extension), that hoauth will try to validate it's uniqueness. -* `alwaysCheckPass` - flag to control password checking for the scenario, when when social network returned email of existing local account. If set to `false` user will be automatically logged in without confirming account with password. (default: `true`) +* `usernameAttribute` - you can specify username attribute, when it has to be unique (like in `yii-user` extension), that hoauth will try to validate its uniqueness. +* `alwaysCheckPass` - flag to control the password checking for the scenario, when the social network has returned the email of an existing local account. If it is set to `false`, the user will be automatically logged in without confirming account with password. (default: `true`) Available Callbacks ------------------- -To make you able to customize the behavior of `hoauth`, it is provide some useful callbacks. Here the list of them: +To make you able to customize the behavior of `hoauth`, it provides some useful callbacks. Here is the list of them: * `Controller::hoauthCheckAccess($user)` * `Controller::hoauthAfterLogin($user)` * `User::findByEmail($email` @@ -185,7 +185,7 @@ To make you able to customize the behavior of `hoauth`, it is provide some usefu `UserOAuth` model ----------------- -`UserOAuth` model used to bind social services to user's account and to store session with social network profile. If you want to use this data (user profile) later, please use `UserOAuth::getProfile()` method: +`UserOAuth` model is used to bind social services to the user's account and to store session with a social network profile. If you want to use this data (the user's profile) later, please use `UserOAuth::getProfile()` method: ```php $userOAuths = UserOAuth::model()->findUser(5); // find all authorizations from user with id=5 foreach($userOAuths as $userOAuth) @@ -200,8 +200,8 @@ $userOAuth = UserOAuth::model()->findUser(5, "Google"); // find all authorizatio $profile = $userOAuth->profile; echo "Your email is {$profile->email} and social network - {$userOAuth->provider}
"; ``` -You can also use `UserOAuth::profileCache` property to access cached copy of the profile, without making any request to the social network. -About how to use HybridAuth object you can read [here](http://hybridauth.sourceforge.net/userguide.html). +You can also use `UserOAuth::profileCache` property to access the cached copy of the profile without making any request to the social network. +[Here](http://hybridauth.sourceforge.net/userguide.html) you can read about using HybridAuth object. Documentation -------------