CWebUser
包 | system.web.auth |
---|---|
继承 | class CWebUser » CApplicationComponent » CComponent |
实现 | IApplicationComponent, IWebUser |
可用自 | 1.0 |
版本 | $Id$ |
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:
- The user provides information needed for authentication.
- An identity instance is created with the user-provided information.
- Call IUserIdentity::authenticate to check if the identity is valid.
- If valid, call CWebUser::login to login the user, and Redirect the user browser to returnUrl.
- 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.
公共属性
属性 | 类型 | 描述 | 被定义在 |
---|---|---|---|
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. | 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 |
公共方法
方法 | 描述 | 被定义在 |
---|---|---|
__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() | CWebUser | |
getIsGuest() | CWebUser | |
getIsInitialized() | 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() | CWebUser | |
hasEvent() | Determines whether an event is defined. | CComponent |
hasEventHandler() | Checks whether the named event has attached handlers. | CComponent |
hasFlash() | 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() | CWebUser | |
setName() | Sets the unique identifier for the user (e.g. username). | CWebUser |
setReturnUrl() | CWebUser | |
setState() | Stores a variable in user session. | CWebUser |
setStateKeyPrefix() | CWebUser |
受保护的方法
方法 | 描述 | 被定义在 |
---|---|---|
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 |
属性详情
whether to enable cookie-based login. Defaults to false.
the name for a guest user. Defaults to 'Guest'. This is used by getName when the current user is a guest (not authenticated).
the unique identifier for the user. If null, it means the user is a guest.
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.
whether the current application user is a guest.
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.
Returns the unique identifier for the user (e.g. username). This is the unique identifier that is mainly used for display purpose.
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.
a prefix for the name of the session variables storing user session data.
方法详情
public mixed __get(string $name)
| ||
$name | string | property name |
{return} | mixed | property value |
PHP magic method. This method is overriden so that persistent states can be accessed like properties.
public void __isset(string $name)
| ||
$name | string | property name |
PHP magic method. This method is overriden so that persistent states can also be checked for null value.
public void __set(string $name, mixed $value)
| ||
$name | string | property name |
$value | mixed | property value |
PHP magic method. This method is overriden so that persistent states can be set like properties.
public void __unset(string $name)
| ||
$name | string | property name |
PHP magic method. This method is overriden so that persistent states can also be unset.
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 |
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.
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. |
Performs access check for this user.
public void clearStates()
|
Clears all user identity information from persistent storage. This will remove the data stored via setState.
protected CHttpCookie createIdentityCookie(string $name)
| ||
$name | string | the cookie name |
{return} | CHttpCookie | the cookie used to store identity information |
Creates a cookie to store identity information.
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 |
Returns a flash message. A flash message is available only in the current and the next requests.
public mixed getId()
| ||
{return} | mixed | the unique identifier for the user. If null, it means the user is a guest. |
public boolean getIsGuest()
| ||
{return} | boolean | whether the current application user is a guest. |
public string getName()
| ||
{return} | string | the user name. If the user is not logged in, this will be guestName. |
Returns the unique identifier for the user (e.g. username). This is the unique identifier that is mainly used for display purpose.
public string getReturnUrl()
| ||
{return} | string | the URL that the user should be redirected to after login. Defaults to the application entry URL. |
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.
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 |
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.
参见
public string getStateKeyPrefix()
| ||
{return} | string | a prefix for the name of the session variables storing user session data. |
public boolean hasFlash(string $key)
| ||
$key | string | key identifying the flash message |
{return} | boolean | whether the specified flash message exists |
public boolean hasState(string $key)
| ||
$key | string | state name |
{return} | boolean | whether there is a state of the specified name. |
Returns a value indicating whether there is a state of the specified name.
public void init()
|
Initializes the application component. This method overrides the parent implementation by starting session, performing cookie-based authentication if enabled, and updating the flash variables.
protected void loadIdentityStates(array $states)
| ||
$states | array | the identity states |
Loads identity states from an array and saves them to persistent storage.
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. |
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.
public void loginRequired()
|
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.
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. |
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.
protected void restoreFromCookie()
|
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.
参见
protected array saveIdentityStates()
| ||
{return} | array | the identity states |
Retrieves identity states from persistent storage and saves them as an array.
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. |
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.
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.) |
Stores a flash message. A flash message is available only in the current and the next requests.
public void setId(mixed $value)
| ||
$value | mixed | the unique identifier for the user. If null, it means the user is a guest. |
public void setName(string $value)
| ||
$value | string | the user name. |
Sets the unique identifier for the user (e.g. username).
参见
public void setReturnUrl(string $value)
| ||
$value | string | the URL that the user should be redirected to after login. |
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 |
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.
参见
public void setStateKeyPrefix(string $value)
| ||
$value | string | a prefix for the name of the session variables storing user session data. |
protected void updateFlash()
|
Updates the internal counters for flash messages. This method is internally used by CWebApplication to maintain the availability of flash messages.