CWebUser

Property Details

absoluteAuthTimeout property (available since v1.1.14)

public integer $absoluteAuthTimeout;

timeout in seconds after which user is logged out regardless of activity.

allowAutoLogin property

public boolean $allowAutoLogin;

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

authTimeout property (available since v1.1.7)

public integer $authTimeout;

timeout in seconds after which user is logged out if inactive. If this property is not set, the user will be logged out after the current session expires (c.f. CHttpSession::timeout).

autoRenewCookie property (available since v1.1.0)

public boolean $autoRenewCookie;

whether to automatically renew the identity cookie each time a page is requested. Defaults to false. This property is effective only when allowAutoLogin is true. When this is false, the identity cookie will expire after the specified duration since the user is initially logged in. When this is true, the identity cookie will expire after the specified duration since the user visits the site the last time.

autoUpdateFlash property (available since v1.1.7)

public boolean $autoUpdateFlash;

whether to automatically update the validity of flash messages. Defaults to true, meaning flash messages will be valid only in the current and the next requests. If this is set false, you will be responsible for ensuring a flash message is deleted after usage. (This can be achieved by calling getFlash with the 3rd parameter being true).

flashes property read-only (available since v1.1.3)

public array getFlashes(boolean $delete=true)

Returns all flash messages. This method is similar to getFlash except that it returns all currently available flash messages.

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)

Returns a value that uniquely represents the user.

identityCookie property

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()

Returns a value indicating whether the user is a guest (not authenticated).

loginRequiredAjaxResponse property (available since v1.1.9)

public string $loginRequiredAjaxResponse;

value that will be echoed in case that user session has expired during an ajax call. When a request is made and user session has expired, loginRequired redirects to loginUrl for login. If that happens during an ajax call, the complete HTML login page is returned as the result of that ajax call. That could be a problem if the ajax call expects the result to be a json array or a predefined string, as the login page is ignored in that case. To solve this, set this property to the desired return value.

If this property is set, this value will be returned as the result of the ajax call in case that the user session has expired.

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.

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(string $defaultUrl=NULL)
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.

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

public mixed __get(string $name)

public function __get($name)
{
    if($this->hasState($name))
        return $this->getState($name);
    else
        return parent::__get($name);
}

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

__isset() method

public boolean __isset(string $name)

public function __isset($name)
{
    if($this->hasState($name))
        return $this->getState($name)!==null;
    else
        return parent::__isset($name);
}

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

__set() method

public void __set(string $name, mixed $value)

public function __set($name,$value)
{
    if($this->hasState($name))
        $this->setState($name,$value);
    else
        parent::__set($name,$value);
}

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

__unset() method

public void __unset(string $name)

public function __unset($name)
{
    if($this->hasState($name))
        $this->setState($name,null);
    else
        parent::__unset($name);
}

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

afterLogin() method (available since v1.1.3)

protected void afterLogin(boolean $fromCookie)

protected function afterLogin($fromCookie)
{
}

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).

afterLogout() method (available since v1.1.3)

protected void afterLogout()

protected function afterLogout()
{
}

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.

beforeLogin() method (available since v1.1.3)

protected boolean beforeLogin(mixed $id, array $states, boolean $fromCookie)

protected function beforeLogin($id,$states,$fromCookie)
{
    return true;
}

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.

beforeLogout() method (available since v1.1.3)

protected boolean beforeLogout()

protected function beforeLogout()
{
    return true;
}

This method is invoked when calling 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.

changeIdentity() method

protected void changeIdentity(mixed $id, string $name, array $states)

protected function changeIdentity($id,$name,$states)
{
    Yii::app()->getSession()->regenerateID(true);
    $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)

public function checkAccess($operation,$params=array(),$allowCaching=true)
{
    if($allowCaching && $params===array() && isset($this->_access[$operation]))
        return $this->_access[$operation];

    $access=Yii::app()->getAuthManager()->checkAccess($operation,$this->getId(),$params);
    if($allowCaching && $params===array())
        $this->_access[$operation]=$access;

    return $access;
}

Performs access check for this user.

clearStates() method

public void clearStates()

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

protected CHttpCookie createIdentityCookie(string $name)

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)

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.

getFlashes() method (available since v1.1.3)

public array getFlashes(boolean $delete=true)

public function getFlashes($delete=true)
{
    $flashes=array();
    $prefix=$this->getStateKeyPrefix().self::FLASH_KEY_PREFIX;
    $keys=array_keys($_SESSION);
    $n=strlen($prefix);
    foreach($keys as $key)
    {
        if(!strncmp($key,$prefix,$n))
        {
            $flashes[substr($key,$n)]=$_SESSION[$key];
            if($delete)
                unset($_SESSION[$key]);
        }
    }
    if($delete)
        $this->setState(self::FLASH_COUNTERS,array());
    return $flashes;
}

Returns all flash messages. This method is similar to getFlash except that it returns all currently available flash messages.

getId() method

public mixed getId()

public function getId()
{
    return $this->getState('__id');
}

Returns a value that uniquely represents the user.

getIsGuest() method

public boolean getIsGuest()

public function getIsGuest()
{
    return $this->getState('__id')===null;
}

Returns a value indicating whether the user is a guest (not authenticated).

getName() method

public string getName()

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(string $defaultUrl=NULL)

public function getReturnUrl($defaultUrl=null)
{
    if($defaultUrl===null)
    {
        $defaultReturnUrl=Yii::app()->getUrlManager()->showScriptName ? Yii::app()->getRequest()->getScriptUrl() : Yii::app()->getRequest()->getBaseUrl().'/';
    }
    else
    {
        $defaultReturnUrl=CHtml::normalizeUrl($defaultUrl);
    }
    return $this->getState('__returnUrl',$defaultReturnUrl);
}

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.

getState() method

public mixed getState(string $key, mixed $defaultValue=NULL)

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.

getStateKeyPrefix() method

public string getStateKeyPrefix()

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)

public function hasFlash($key)
{
    return $this->getFlash($key, null, false)!==null;
}

hasState() method

public boolean hasState(string $key)

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()

public function init()
{
    parent::init();
    Yii::app()->getSession()->open();
    if($this->getIsGuest() && $this->allowAutoLogin)
        $this->restoreFromCookie();
    elseif($this->autoRenewCookie && $this->allowAutoLogin)
        $this->renewCookie();
    if($this->autoUpdateFlash)
        $this->updateFlash();

    $this->updateAuthStatus();
}

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)

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 boolean login(IUserIdentity $identity, integer $duration=0)

public function login($identity,$duration=0)
{
    $id=$identity->getId();
    $states=$identity->getPersistentStates();
    if($this->beforeLogin($id,$states,false))
    {
        $this->changeIdentity($id,$identity->getName(),$states);

        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))));
        }

        if ($this->absoluteAuthTimeout)
            $this->setState(self::AUTH_ABSOLUTE_TIMEOUT_VAR, time()+$this->absoluteAuthTimeout);
        $this->afterLogin(false);
    }
    return !$this->getIsGuest();
}

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()

public function loginRequired()
{
    $app=Yii::app();
    $request=$app->getRequest();

    if(!$request->getIsAjaxRequest())
    {
        $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);
        }
    }
    elseif(isset($this->loginRequiredAjaxResponse))
    {
        echo $this->loginRequiredAjaxResponse;
        Yii::app()->end();
    }

    throw new CHttpException(403,Yii::t('yii','Login Required'));
}

Redirects the user browser to the login page. Before the redirection, the current URL (if it's not an AJAX 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)

public function logout($destroySession=true)
{
    if($this->beforeLogout())
    {
        if($this->allowAutoLogin)
        {
            Yii::app()->getRequest()->getCookies()->remove($this->getStateKeyPrefix());
            if($this->identityCookie!==null)
            {
                $cookie=$this->createIdentityCookie($this->getStateKeyPrefix());
                $cookie->value=null;
                $cookie->expire=0;
                Yii::app()->getRequest()->getCookies()->add($cookie->name,$cookie);
            }
        }
        if($destroySession)
            Yii::app()->getSession()->destroy();
        else
            $this->clearStates();
        $this->_access=array();
        $this->afterLogout();
    }
}

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.

renewCookie() method (available since v1.1.3)

protected void renewCookie()

protected function renewCookie()
{
    $request=Yii::app()->getRequest();
    $cookies=$request->getCookies();
    $cookie=$cookies->itemAt($this->getStateKeyPrefix());
    if($cookie && !empty($cookie->value) && ($data=Yii::app()->getSecurityManager()->validateData($cookie->value))!==false)
    {
        $data=@unserialize($data);
        if(is_array($data) && isset($data[0],$data[1],$data[2],$data[3]))
        {
            $this->saveToCookie($data[2]);
        }
    }
}

Renews the identity cookie. This method will set the expiration time of the identity cookie to be the current time plus the originally specified cookie duration.

restoreFromCookie() method

protected void restoreFromCookie()

protected function restoreFromCookie()
{
    $app=Yii::app();
    $request=$app->getRequest();
    $cookie=$request->getCookies()->itemAt($this->getStateKeyPrefix());
    if($cookie && !empty($cookie->value) && is_string($cookie->value) && ($data=$app->getSecurityManager()->validateData($cookie->value))!==false)
    {
        $data=@unserialize($data);
        if(is_array($data) && isset($data[0],$data[1],$data[2],$data[3]))
        {
            list($id,$name,$duration,$states)=$data;
            if($this->beforeLogin($id,$states,true))
            {
                $this->changeIdentity($id,$name,$states);
                if($this->autoRenewCookie)
                {
                    $this->saveToCookie($duration);
                }
                $this->afterLogin(true);
            }
        }
    }
}

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.

saveIdentityStates() method

protected array saveIdentityStates()

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)

protected function saveToCookie($duration)
{
    $app=Yii::app();
    $cookie=$this->createIdentityCookie($this->getStateKeyPrefix());
    $cookie->expire=time()+$duration;
    $data=array(
        $this->getId(),
        $this->getName(),
        $duration,
        $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.

setFlash() method

public void setFlash(string $key, mixed $value, mixed $defaultValue=NULL)

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)

public function setId($value)
{
    $this->setState('__id',$value);
}

setName() method

public void setName(string $value)

public function setName($value)
{
    $this->setState('__name',$value);
}

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

setReturnUrl() method

public void setReturnUrl(string $value)

public function setReturnUrl($value)
{
    $this->setState('__returnUrl',$value);
}

setState() method

public void setState(string $key, mixed $value, mixed $defaultValue=NULL)

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.

setStateKeyPrefix() method

public void setStateKeyPrefix(string $value)

public function setStateKeyPrefix($value)
{
    $this->_keyPrefix=$value;
}

updateAuthStatus() method (available since v1.1.7)

protected void updateAuthStatus()

protected function updateAuthStatus()
{
    if(($this->authTimeout!==null || $this->absoluteAuthTimeout!==null) && !$this->getIsGuest())
    {
        $expires=$this->getState(self::AUTH_TIMEOUT_VAR);
        $expiresAbsolute=$this->getState(self::AUTH_ABSOLUTE_TIMEOUT_VAR);

        if ($expires!==null && $expires < time() || $expiresAbsolute!==null && $expiresAbsolute < time())
            $this->logout(false);
        else
            $this->setState(self::AUTH_TIMEOUT_VAR,time()+$this->authTimeout);
    }
}

Updates the authentication status according to authTimeout. If the user has been inactive for authTimeout seconds, or {link absoluteAuthTimeout} has passed, he will be automatically logged out.

updateFlash() method

protected void updateFlash()

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.