* The user identity information will be saved in storage that is
* persistent during the user session. By default, the storage is simply
* the session storage. If the duration parameter is greater than 0,
* a cookie will be sent to prepare for cookie-based login in future.
*
* Note, you have to set {@link enableAutoLogin} to true
* if you want to allow user to be authenticated based on the cookie information.
* This method stores the necessary session information to keep track
* of the user identity information. If `$duration` is greater than 0
* and [[enableAutoLogin]] is true, it will also send out an identity
* cookie to support cookie-based login.
*
* @param Identity $identity the user identity (which should already be authenticated)
* @param integer $duration number of seconds that the user can remain in logged-in status. Defaults to 0, meaning login till the user closes the browser.
* If greater than 0, cookie-based login will be used. In this case, {@link enableAutoLogin}
* must be set true, otherwise an exception will be thrown.
* @param integer $duration number of seconds that the user can remain in logged-in status.
* Defaults to 0, meaning login till the user closes the browser or the session is manually destroyed.
* If greater than 0 and [[enableAutoLogin]] is true, cookie-based login will be supported.
* @return boolean whether the user is logged in
*/
public function login($identity, $duration = 0)
@ -150,11 +159,10 @@ class User extends Component
}
/**
* Populates the current user object with the information obtained from cookie.
* This method is used when automatic login ({@link enableAutoLogin}) is enabled.
* The user identity information is recovered from cookie.
* Sufficient security measures are used to prevent cookie data from being tampered.
* @see sendIdentityCookie
* Logs in a user by cookie.
*
* This method attempts to log in a user using the ID and authKey information
* provided by the given cookie.
*/
protected function loginByCookie()
{
@ -185,9 +193,8 @@ class User extends Component
/**
* Logs out the current user.
* This will remove authentication-related session data.
* If the parameter is true, the whole session will be destroyed as well.
* @param boolean $destroySession whether to destroy the whole session. Defaults to true. If false,
* then {@link clearStates} will be called, which removes only the data stored via {@link setState}.
* If `$destroySession` is true, all session data will be removed.
* @param boolean $destroySession whether to destroy the whole session. Defaults to true.
*/
public function logout($destroySession = true)
{
@ -215,73 +222,63 @@ class User extends Component
/**
* Returns a value that uniquely represents the user.
* @return mixed the unique identifier for the user. If null, it means the user is a guest.
* @return string|integer the unique identifier for the user. If null, it means the user is a guest.
throw new HttpException(403, Yii::t('yii|Login Required'));
}
@ -289,21 +286,18 @@ class User extends Component
/**
* This method is called before logging in a user.
* You may override this method to provide additional security check.
* For example, when the login is cookie-based, you may want to verify
* that the user ID together with a random token in the states can be found
* in the database. This will prevent hackers from faking arbitrary
* identity cookies even if they crack down the server private key.
* @param mixed $id the user ID. This is the same as returned by {@link getId()}.
* @param array $states a set of name-value pairs that are provided by the user identity.
* @param boolean $fromCookie whether the login is based on cookie
* @return boolean whether the user should be logged in
* The default implementation will trigger the [[EVENT_BEFORE_LOGIN]] event.
* If you override this method, make sure you call the parent implementation
* so that the event is triggered.
* @param Identity $identity the user identity information
* @param boolean $cookieBased whether the login is cookie-based
* @return boolean whether the user should continue to be logged in
*/
protected function beforeLogin($identity, $fromCookie)
protected function beforeLogin($identity, $cookieBased)
{
$event = new UserEvent(array(
'identity' => $identity,
'fromCookie' => $fromCookie,
'cookieBased' => $cookieBased,
));
$this->trigger(self::EVENT_BEFORE_LOGIN, $event);
return $event->isValid;
@ -311,24 +305,27 @@ class User extends Component
/**
* This method is called after the user is successfully logged in.
* You may override this method to do some postprocessing (e.g. log the user
* login IP and time; load the user permission information).
* @param boolean $fromCookie whether the login is based on cookie.
* The default implementation will trigger the [[EVENT_AFTER_LOGIN]] event.
* If you override this method, make sure you call the parent implementation
* so that the event is triggered.
* @param Identity $identity the user identity information
* @param boolean $cookieBased whether the login is cookie-based
*/
protected function afterLogin($identity, $fromCookie)
protected function afterLogin($identity, $cookieBased)
{
$this->trigger(self::EVENT_AFTER_LOGIN, new UserEvent(array(
'identity' => $identity,
'fromCookie' => $fromCookie,
'cookieBased' => $cookieBased,
)));
}
/**
* This method is invoked when calling {@link logout} to log out a user.
* If this method return false, the logout action will be cancelled.
* You may override this method to provide additional check before
* logging out a user.
* @return boolean whether to log out the user
* This method is invoked when calling [[logout()]] to log out a user.
* The default implementation will trigger the [[EVENT_BEFORE_LOGOUT]] event.
* If you override this method, make sure you call the parent implementation
* so that the event is triggered.
* @param Identity $identity the user identity information
* @return boolean whether the user should continue to be logged out
*/
protected function beforeLogout($identity)
{
@ -340,8 +337,11 @@ class User extends Component
}
/**
* This method is invoked right after a user is logged out.
* You may override this method to do some extra cleanup work for the user.
* This method is invoked right after a user is logged out via [[logout()]].
* The default implementation will trigger the [[EVENT_AFTER_LOGOUT]] event.
* If you override this method, make sure you call the parent implementation
* so that the event is triggered.
* @param Identity $identity the user identity information
*/
protected function afterLogout($identity)
{
@ -350,7 +350,6 @@ class User extends Component
)));
}
/**
* Renews the identity cookie.
* This method will set the expiration time of the identity cookie to be the current time
@ -372,12 +371,12 @@ class User extends Component
}
/**
* Saves necessary user data into a cookie.
* This method is used when automatic login ({@link enableAutoLogin}) is enabled.
* This method saves user ID, username, other identity states and a validation key to cookie.
* These information are used to do authentication next time when user visits the application.
* Sends an identity cookie.
* This method is used when [[enableAutoLogin]] is true.
* It saves [[id]], [[Identity::getAuthKey()|auth key]], and the duration of cookie-based login
* information in the cookie.
* @param Identity $identity
* @param integer $duration number of seconds that the user can remain in logged-in status. Defaults to 0, meaning login till the user closes the browser.
* @param integer $duration number of seconds that the user can remain in logged-in status.
* @see loginByCookie
*/
protected function sendIdentityCookie($identity, $duration)
@ -394,42 +393,40 @@ class User extends Component
/**
* Changes the current user with the specified identity information.
* This method is called by {@link login} and {@link restoreFromCookie}
* when the current user needs to be populated with the corresponding
* identity information. Derived classes may override this method
* by retrieving additional user-related information. Make sure the
* parent implementation is called first.
* @param Identity $identity a unique identifier for the user
* This method is called by [[login()]] and [[loginByCookie()]]
* when the current user needs to be associated with the corresponding
* identity information.
* @param Identity $identity the identity information to be associated with the current user.
Qiang Xue
12 years ago