0 follower

CWebUser

Package system.web.auth
Inheritance class CWebUser » CApplicationComponent » CComponent
Implements IApplicationComponent, IWebUser
Since 1.0
Version $Id$
Source Code framework/web/auth/CWebUser.php
CWebUser represents the persistent state for a Web application user.

CWebUser is used as an application component whose ID is 'user'. Therefore, at any place one can access the user state via Yii::app()->user.

CWebUser should be used together with an identity which implements the actual authentication algorithm.

A typical authentication process using CWebUser is as follows:
  1. The user provides information needed for authentication.
  2. An identity instance is created with the user-provided information.
  3. Call IUserIdentity::authenticate to check if the identity is valid.
  4. If valid, call CWebUser::login to login the user, and Redirect the user browser to returnUrl.
  5. If not valid, retrieve the error code or message from the identity instance and display it.


The property id and name are both unique identifiers for the user. The former is mainly used internally (e.g. primary key), while the latter is for display purpose (e.g. username). is a unique identifier for a user that is persistent during the whole user session. It can be a username, or something else, depending on the implementation of the identity class.

Both id and name are persistent during the user session. Besides, an identity may have additional persistent data which can be accessed by calling getState. Note, when cookie-based authentication is enabled, all these persistent data will be stored in cookie. Therefore, do not store password or other sensitive data in the persistent storage. Instead, you should store them directly in session on the server side if needed.

Public Properties

Hide inherited properties

PropertyTypeDescriptionDefined By
allowAutoLogin boolean whether to enable cookie-based login. CWebUser
behaviors array the behaviors that should be attached to this component. CApplicationComponent
guestName string the name for a guest user. CWebUser
id mixed the unique identifier for the user. CWebUser
identityCookie array the property values (in name-value pairs) used to initialize the identity cookie. CWebUser
isGuest boolean whether the current application user is a guest. CWebUser
isInitialized boolean whether this application component has been initialized (i.e., init() is invoked. CApplicationComponent
loginUrl string|array the URL for login. CWebUser
name string Returns the unique identifier for the user (e.g. username). CWebUser
returnUrl string Returns the URL that the user should be redirected to after successful login. CWebUser
stateKeyPrefix string a prefix for the name of the session variables storing user session data. CWebUser

Public Methods

Hide inherited methods

MethodDescriptionDefined By
__call() Calls the named method which is not a class method. CComponent
__get() PHP magic method. CWebUser
__isset() PHP magic method. CWebUser
__set() PHP magic method. CWebUser
__unset() PHP magic method. CWebUser
asa() Returns the named behavior object. CComponent
attachBehavior() Attaches a behavior to this component. CComponent
attachBehaviors() Attaches a list of behaviors to the component. CComponent
attachEventHandler() Attaches an event handler to an event. CComponent
canGetProperty() Determines whether a property can be read. CComponent
canSetProperty() Determines whether a property can be set. CComponent
checkAccess() Performs access check for this user. CWebUser
clearStates() Clears all user identity information from persistent storage. CWebUser
detachBehavior() Detaches a behavior from the component. CComponent
detachBehaviors() Detaches all behaviors from the component. CComponent
detachEventHandler() Detaches an existing event handler. CComponent
disableBehavior() Disables an attached behavior. CComponent
disableBehaviors() Disables all behaviors attached to this component. CComponent
enableBehavior() Enables an attached behavior. CComponent
enableBehaviors() Enables all behaviors attached to this component. CComponent
getEventHandlers() Returns the list of attached event handlers for an event. CComponent
getFlash() Returns a flash message. CWebUser
getId() Returns the unique identifier for the user. If null, it means the user is a guest. CWebUser
getIsGuest() Checks whether the current application user is a guest. CWebUser
getIsInitialized() Checks whether this application component has been initialized (i.e., init() is invoked.) CApplicationComponent
getName() Returns the unique identifier for the user (e.g. username). CWebUser
getReturnUrl() Returns the URL that the user should be redirected to after successful login. CWebUser
getState() Returns the value of a variable that is stored in user session. CWebUser
getStateKeyPrefix() Returns a prefix for the name of the session variables storing user session data. CWebUser
hasEvent() Determines whether an event is defined. CComponent
hasEventHandler() Checks whether the named event has attached handlers. CComponent
hasFlash() Determines whether the specified flash message exists CWebUser
hasProperty() Determines whether a property is defined. CComponent
hasState() Returns a value indicating whether there is a state of the specified name. CWebUser
init() Initializes the application component. CWebUser
login() Logs in a user. CWebUser
loginRequired() Redirects the user browser to the login page. CWebUser
logout() Logs out the current user. CWebUser
raiseEvent() Raises an event. CComponent
setFlash() Stores a flash message. CWebUser
setId() Sets the unique identifier for the user. If null, it means the user is a guest. CWebUser
setName() Sets the unique identifier for the user (e.g. username). CWebUser
setReturnUrl() Sets the URL that the user should be redirected to after login. CWebUser
setState() Stores a variable in user session. CWebUser
setStateKeyPrefix() Sets a prefix for the name of the session variables storing user session data. CWebUser

Protected Methods

Hide inherited methods

MethodDescriptionDefined By
changeIdentity() Changes the current user with the specified identity information. CWebUser
createIdentityCookie() Creates a cookie to store identity information. CWebUser
loadIdentityStates() Loads identity states from an array and saves them to persistent storage. CWebUser
restoreFromCookie() Populates the current user object with the information obtained from cookie. CWebUser
saveIdentityStates() Retrieves identity states from persistent storage and saves them as an array. CWebUser
saveToCookie() Saves necessary user data into a cookie. CWebUser
updateFlash() Updates the internal counters for flash messages. CWebUser

Property Details

allowAutoLogin property
public boolean $allowAutoLogin;

whether to enable cookie-based login. Defaults to false.

guestName property
public string $guestName;

the name for a guest user. Defaults to 'Guest'. This is used by getName when the current user is a guest (not authenticated).

id property
public mixed getId()
public void setId(mixed $value)

the unique identifier for the user. If null, it means the user is a guest.

identityCookie property (available since v1.0.5)
public array $identityCookie;

the property values (in name-value pairs) used to initialize the identity cookie. Any property of CHttpCookie may be initialized. This property is effective only when allowAutoLogin is true.

isGuest property read-only
public boolean getIsGuest()

whether the current application user is a guest.

loginUrl property
public string|array $loginUrl;

the URL for login. If using array, the first element should be the route to the login action, and the rest name-value pairs are GET parameters to construct the login URL (e.g. array('/site/login')). If this property is null, a 403 HTTP exception will be raised instead.

See Also

name property
public string getName()
public void setName(string $value)

Returns the unique identifier for the user (e.g. username). This is the unique identifier that is mainly used for display purpose.

returnUrl property
public string getReturnUrl()
public void setReturnUrl(string $value)

Returns the URL that the user should be redirected to after successful login. This property is usually used by the login action. If the login is successful, the action should read this property and use it to redirect the user browser.

See Also

stateKeyPrefix property
public string getStateKeyPrefix()
public void setStateKeyPrefix(string $value)

a prefix for the name of the session variables storing user session data.

Method Details

__get() method (available since v1.0.3)
public mixed __get(string $name)
$name string property name
{return} mixed property value
Source Code: framework/web/auth/CWebUser.php#92 (show)
public function __get($name)
{
    if($this->hasState($name))
        return $this->getState($name);
    else
        return parent::__get($name);
}

PHP magic method. This method is overriden so that persistent states can be accessed like properties.

__isset() method (available since v1.0.3)
public void __isset(string $name)
$name string property name
Source Code: framework/web/auth/CWebUser.php#121 (show)
public function __isset($name)
{
    if($this->hasState($name))
        return $this->getState($name)!==null;
    else
        return parent::__isset($name);
}

PHP magic method. This method is overriden so that persistent states can also be checked for null value.

__set() method (available since v1.0.3)
public void __set(string $name, mixed $value)
$name string property name
$value mixed property value
Source Code: framework/web/auth/CWebUser.php#107 (show)
public function __set($name,$value)
{
    if($this->hasState($name))
        $this->setState($name,$value);
    else
        parent::__set($name,$value);
}

PHP magic method. This method is overriden so that persistent states can be set like properties.

__unset() method (available since v1.0.3)
public void __unset(string $name)
$name string property name
Source Code: framework/web/auth/CWebUser.php#136 (show)
public function __unset($name)
{
    if($this->hasState($name))
        $this->setState($name,null);
    else
        parent::__unset($name);
}

PHP magic method. This method is overriden so that persistent states can also be unset.

changeIdentity() method
protected void changeIdentity(mixed $id, string $name, array $states)
$id mixed a unique identifier for the user
$name string the display name for the user
$states array identity states
Source Code: framework/web/auth/CWebUser.php#509 (show)
protected function changeIdentity($id,$name,$states)
{
    $this->setId($id);
    $this->setName($name);
    $this->loadIdentityStates($states);
}

Changes the current user with the specified identity information. This method is called by login and 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.

checkAccess() method
public boolean checkAccess(string $operation, array $params=array ( ), boolean $allowCaching=true)
$operation string the name of the operation that need access check.
$params array name-value pairs that would be passed to business rules associated with the tasks and roles assigned to the user.
$allowCaching boolean whether to allow caching the result of access checki. This parameter has been available since version 1.0.5. When this parameter is true (default), if the access check of an operation was performed before, its result will be directly returned when calling this method to check the same operation. If this parameter is false, this method will always call CAuthManager::checkAccess to obtain the up-to-date access result. Note that this caching is effective only within the same request.
{return} boolean whether the operations can be performed by this user.
Source Code: framework/web/auth/CWebUser.php#583 (show)
public function checkAccess($operation,$params=array(),$allowCaching=true)
{
    if($allowCaching && isset($this->_access[$operation]))
        return $this->_access[$operation];
    else
        return $this->_access[$operation]=Yii::app()->getAuthManager()->checkAccess($operation,$this->getId(),$params);
}

Performs access check for this user.

clearStates() method
public void clearStates()
Source Code: framework/web/auth/CWebUser.php#441 (show)
public function clearStates()
{
    $keys=array_keys($_SESSION);
    $prefix=$this->getStateKeyPrefix();
    $n=strlen($prefix);
    foreach($keys as $key)
    {
        if(!strncmp($key,$prefix,$n))
            unset($_SESSION[$key]);
    }
}

Clears all user identity information from persistent storage. This will remove the data stored via setState.

createIdentityCookie() method (available since v1.0.5)
protected CHttpCookie createIdentityCookie(string $name)
$name string the cookie name
{return} CHttpCookie the cookie used to store identity information
Source Code: framework/web/auth/CWebUser.php#350 (show)
protected function createIdentityCookie($name)
{
    $cookie=new CHttpCookie($name,'');
    if(is_array($this->identityCookie))
    {
        foreach($this->identityCookie as $name=>$value)
            $cookie->$name=$value;
    }
    return $cookie;
}

Creates a cookie to store identity information.

getFlash() method
public mixed getFlash(string $key, mixed $defaultValue=NULL, boolean $delete=true)
$key string key identifying the flash message
$defaultValue mixed value to be returned if the flash message is not available.
$delete boolean whether to delete this flash message after accessing it. Defaults to true. This parameter has been available since version 1.0.2.
{return} mixed the message message
Source Code: framework/web/auth/CWebUser.php#462 (show)
public function getFlash($key,$defaultValue=null,$delete=true)
{
    $value=$this->getState(self::FLASH_KEY_PREFIX.$key,$defaultValue);
    if($delete)
        $this->setFlash($key,null);
    return $value;
}

Returns a flash message. A flash message is available only in the current and the next requests.

getId() method
public mixed getId()
{return} mixed the unique identifier for the user. If null, it means the user is a guest.
Source Code: framework/web/auth/CWebUser.php#218 (show)
public function getId()
{
    return $this->getState('__id');
}

getIsGuest() method
public boolean getIsGuest()
{return} boolean whether the current application user is a guest.
Source Code: framework/web/auth/CWebUser.php#210 (show)
public function getIsGuest()
{
    return $this->getState('__id')===null;
}

getName() method
public string getName()
{return} string the user name. If the user is not logged in, this will be guestName.
Source Code: framework/web/auth/CWebUser.php#236 (show)
public function getName()
{
    if(($name=$this->getState('__name'))!==null)
        return $name;
    else
        return $this->guestName;
}

Returns the unique identifier for the user (e.g. username). This is the unique identifier that is mainly used for display purpose.

getReturnUrl() method
public string getReturnUrl()
{return} string the URL that the user should be redirected to after login. Defaults to the application entry URL.
Source Code: framework/web/auth/CWebUser.php#261 (show)
public function getReturnUrl()
{
    return $this->getState('__returnUrl',Yii::app()->getRequest()->getScriptUrl());
}

Returns the URL that the user should be redirected to after successful login. This property is usually used by the login action. If the login is successful, the action should read this property and use it to redirect the user browser.

See Also

getState() method
public mixed getState(string $key, mixed $defaultValue=NULL)
$key string variable name
$defaultValue mixed default value
{return} mixed the value of the variable. If it doesn't exist in the session, the provided default value will be returned
Source Code: framework/web/auth/CWebUser.php#395 (show)
public function getState($key,$defaultValue=null)
{
    $key=$this->getStateKeyPrefix().$key;
    return isset($_SESSION[$key]) ? $_SESSION[$key] : $defaultValue;
}

Returns the value of a variable that is stored in user session.

This function is designed to be used by CWebUser descendant classes who want to store additional user information in user session. A variable, if stored in user session using setState can be retrieved back using this function.

See Also

getStateKeyPrefix() method
public string getStateKeyPrefix()
{return} string a prefix for the name of the session variables storing user session data.
Source Code: framework/web/auth/CWebUser.php#364 (show)
public function getStateKeyPrefix()
{
    if($this->_keyPrefix!==null)
        return $this->_keyPrefix;
    else
        return $this->_keyPrefix=md5('Yii.'.get_class($this).'.'.Yii::app()->getId());
}

hasFlash() method
public boolean hasFlash(string $key)
$key string key identifying the flash message
{return} boolean whether the specified flash message exists
Source Code: framework/web/auth/CWebUser.php#493 (show)
public function hasFlash($key)
{
    return $this->getFlash($key, null, false)!==null;
}

hasState() method (available since v1.0.3)
public boolean hasState(string $key)
$key string state name
{return} boolean whether there is a state of the specified name.
Source Code: framework/web/auth/CWebUser.php#431 (show)
public function hasState($key)
{
    $key=$this->getStateKeyPrefix().$key;
    return isset($_SESSION[$key]);
}

Returns a value indicating whether there is a state of the specified name.

init() method
public void init()
Source Code: framework/web/auth/CWebUser.php#149 (show)
public function init()
{
    parent::init();
    Yii::app()->getSession()->open();
    if($this->getIsGuest() && $this->allowAutoLogin)
        $this->restoreFromCookie();
    $this->updateFlash();
}

Initializes the application component. This method overrides the parent implementation by starting session, performing cookie-based authentication if enabled, and updating the flash variables.

loadIdentityStates() method
protected void loadIdentityStates(array $states)
$states array the identity states
Source Code: framework/web/auth/CWebUser.php#532 (show)
protected function loadIdentityStates($states)
{
    $names=array();
    if(is_array($states))
    {
        foreach($states as $name=>$value)
        {
            $this->setState($name,$value);
            $names[$name]=true;
        }
    }
    $this->setState(self::STATES_VAR,$names);
}

Loads identity states from an array and saves them to persistent storage.

login() method
public void login(IUserIdentity $identity, integer $duration=0)
$identity IUserIdentity the user identity (which should already be authenticated)
$duration integer 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, allowAutoLogin must be set true, otherwise an exception will be thrown.
Source Code: framework/web/auth/CWebUser.php#174 (show)
public function login($identity,$duration=0)
{
    $this->changeIdentity($identity->getId(),$identity->getName(),$identity->getPersistentStates());

    if($duration>0)
    {
        if($this->allowAutoLogin)
            $this->saveToCookie($duration);
        else
            throw new CException(Yii::t('yii','{class}.allowAutoLogin must be set true in order to use cookie-based authentication.',
                array('{class}'=>get_class($this))));
    }
}

Logs in a user.

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 allowAutoLogin to true if you want to allow user to be authenticated based on the cookie information.

loginRequired() method
public void loginRequired()
Source Code: framework/web/auth/CWebUser.php#282 (show)
public function loginRequired()
{
    $app=Yii::app();
    $request=$app->getRequest();
    $this->setReturnUrl($request->getUrl());
    if(($url=$this->loginUrl)!==null)
    {
        if(is_array($url))
        {
            $route=isset($url[0]) ? $url[0] : $app->defaultController;
            $url=$app->createUrl($route,array_splice($url,1));
        }
        $request->redirect($url);
    }
    else
        throw new CHttpException(403,Yii::t('yii','Login Required'));
}

Redirects the user browser to the login page. Before the redirection, the current URL will be kept in returnUrl so that the user browser may be redirected back to the current page after successful login. Make sure you set loginUrl so that the user browser can be redirected to the specified login URL after calling this method. After calling this method, the current request processing will be terminated.

logout() method
public void logout(boolean $destroySession=true)
$destroySession boolean whether to destroy the whole session. Defaults to true. If false, then clearStates will be called, which removes only the data stored via setState. This parameter has been available since version 1.0.7. Before 1.0.7, the behavior is to destroy the whole session.
Source Code: framework/web/auth/CWebUser.php#197 (show)
public function logout($destroySession=true)
{
    if($this->allowAutoLogin)
        Yii::app()->getRequest()->getCookies()->remove($this->getStateKeyPrefix());
    if($destroySession)
        Yii::app()->getSession()->destroy();
    else
        $this->clearStates();
}

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.

restoreFromCookie() method
protected void restoreFromCookie()
Source Code: framework/web/auth/CWebUser.php#307 (show)
protected function restoreFromCookie()
{
    $app=Yii::app();
    $cookie=$app->getRequest()->getCookies()->itemAt($this->getStateKeyPrefix());
    if($cookie && !empty($cookie->value) && ($data=$app->getSecurityManager()->validateData($cookie->value))!==false)
    {
        $data=@unserialize($data);
        if(is_array($data) && isset($data[0],$data[1],$data[2]))
        {
            list($id,$name,$states)=$data;
            $this->changeIdentity($id,$name,$states);
        }
    }
}

Populates the current user object with the information obtained from cookie. This method is used when automatic login (allowAutoLogin) is enabled. The user identity information is recovered from cookie. Sufficient security measures are used to prevent cookie data from being tampered.

See Also

saveIdentityStates() method
protected array saveIdentityStates()
{return} array the identity states
Source Code: framework/web/auth/CWebUser.php#520 (show)
protected function saveIdentityStates()
{
    $states=array();
    foreach($this->getState(self::STATES_VAR,array()) as $name=>$dummy)
        $states[$name]=$this->getState($name);
    return $states;
}

Retrieves identity states from persistent storage and saves them as an array.

saveToCookie() method
protected void saveToCookie(integer $duration)
$duration integer number of seconds that the user can remain in logged-in status. Defaults to 0, meaning login till the user closes the browser.
Source Code: framework/web/auth/CWebUser.php#330 (show)
protected function saveToCookie($duration)
{
    $app=Yii::app();
    $cookie=$this->createIdentityCookie($this->getStateKeyPrefix());
    $cookie->expire=time()+$duration;
    $data=array(
        $this->getId(),
        $this->getName(),
        $this->saveIdentityStates(),
    );
    $cookie->value=$app->getSecurityManager()->hashData(serialize($data));
    $app->getRequest()->getCookies()->add($cookie->name,$cookie);
}

Saves necessary user data into a cookie. This method is used when automatic login (allowAutoLogin) 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.

See Also

setFlash() method
public void setFlash(string $key, mixed $value, mixed $defaultValue=NULL)
$key string key identifying the flash message
$value mixed flash message
$defaultValue mixed if this value is the same as the flash message, the flash message will be removed. (Therefore, you can use setFlash('key',null) to remove a flash message.)
Source Code: framework/web/auth/CWebUser.php#478 (show)
public function setFlash($key,$value,$defaultValue=null)
{
    $this->setState(self::FLASH_KEY_PREFIX.$key,$value,$defaultValue);
    $counters=$this->getState(self::FLASH_COUNTERS,array());
    if($value===$defaultValue)
        unset($counters[$key]);
    else
        $counters[$key]=0;
    $this->setState(self::FLASH_COUNTERS,$counters,array());
}

Stores a flash message. A flash message is available only in the current and the next requests.

setId() method
public void setId(mixed $value)
$value mixed the unique identifier for the user. If null, it means the user is a guest.
Source Code: framework/web/auth/CWebUser.php#226 (show)
public function setId($value)
{
    $this->setState('__id',$value);
}

setName() method
public void setName(string $value)
$value string the user name.
Source Code: framework/web/auth/CWebUser.php#249 (show)
public function setName($value)
{
    $this->setState('__name',$value);
}

Sets the unique identifier for the user (e.g. username).

See Also

setReturnUrl() method
public void setReturnUrl(string $value)
$value string the URL that the user should be redirected to after login.
Source Code: framework/web/auth/CWebUser.php#269 (show)
public function setReturnUrl($value)
{
    $this->setState('__returnUrl',$value);
}

setState() method
public void setState(string $key, mixed $value, mixed $defaultValue=NULL)
$key string variable name
$value mixed variable value
$defaultValue mixed default value. If $value===$defaultValue, the variable will be removed from the session
Source Code: framework/web/auth/CWebUser.php#416 (show)
public function setState($key,$value,$defaultValue=null)
{
    $key=$this->getStateKeyPrefix().$key;
    if($value===$defaultValue)
        unset($_SESSION[$key]);
    else
        $_SESSION[$key]=$value;
}

Stores a variable in user session.

This function is designed to be used by CWebUser descendant classes who want to store additional user information in user session. By storing a variable using this function, the variable may be retrieved back later using getState. The variable will be persistent across page requests during a user session.

See Also

setStateKeyPrefix() method (available since v1.0.9)
public void setStateKeyPrefix(string $value)
$value string a prefix for the name of the session variables storing user session data.
Source Code: framework/web/auth/CWebUser.php#376 (show)
public function setStateKeyPrefix($value)
{
    $this->_keyPrefix=$value;
}

updateFlash() method
protected void updateFlash()
Source Code: framework/web/auth/CWebUser.php#551 (show)
protected function updateFlash()
{
    $counters=$this->getState(self::FLASH_COUNTERS);
    if(!is_array($counters))
        return;
    foreach($counters as $key=>$count)
    {
        if($count)
        {
            unset($counters[$key]);
            $this->setState(self::FLASH_KEY_PREFIX.$key,null);
        }
        else
            $counters[$key]++;
    }
    $this->setState(self::FLASH_COUNTERS,$counters,array());
}

Updates the internal counters for flash messages. This method is internally used by CWebApplication to maintain the availability of flash messages.