Path

ez components / documentation / api reference / 2009.2.1 / mvcauthenticationtiein


eZ Components 2009.2.1

MvcAuthenticationTiein: ezcMvcAuthenticationFilter

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcMvcAuthenticationFilter

This class provides a filter that applications can use for authentication. [source]
Through the $options argument to the controller you can configure many aspects of this filter. By default a few settings are made that setup table names and fields names, as well as names of variables under which certain bits of the filter will be available in the controller's actions. The filter needs to be integrated in both the applications configuration (through an implementation of ezcMvcDispatcherConfiguration) as well as in the controller handling authentication actions. Please refer to the tutorial on how to do this.
Some of the defaults provided in this filter can easily be changed by inheriting. For example if you want to change the password generation algorithm you need to override generatePassword(). Another example is when you want other authentication methods besides session and database. In that case setupAuth() needs to be overridden in an inherited class.

Method Summary

public ezcMvcAuthenticationFilter __construct( [$options = null] )
Constructs a new ezcMvcAuthenticationFilter object
public bool checkUserExists( $username )
Checks whether a user exists in the database.
public void createUser( $username, $password, $extraInfo )
Creates an entry in the user database table for $username and $password.
protected string fetchUserName( )
Returns the username associated with the user ID as stored in the session.
public string generatePassword( $username )
Returns a generated basic password depending on the $username.
public ezcMvcAuthenticationFilterOptions getOptions( )
Returns the currently set options
protected string hashPassword( $password )
Returns the hashed version of the clear text password
public void login( $request, $user, $password )
Method to be called from the controller's login action to log a user in.
public void logout( $request )
Method to be called from the controller's logout action to log a user out.
public void processLoginRequired( $res, $reasons, [$errorMap = null], $result )
Checks the status from the authentication run and adds the reasons as variable to the $result.
public ezcMvcInternalRedirect|ezcMvcResult returnLoginRedirect( $authentication, $request, $redirUrl )
Returns either an internal or external redirect depending on whether the user authenticated succesfully.
public ezcMvcResult returnLogoutRedirect( $request )
Returns an external redirect depending to the configured logoutUri.
public void runAuthCheckLoggedIn( $request )
Sets up the authentication mechanism to be used for routes that do not require authentication.
public void runAuthRequiredFilter( $request )
Sets up the authentication mechanism to be used for routes that do require authentication.
public void setOptions( $options )
Sets a new options object
protected ezcAuthentication setupAuth( [$user = null], [$password = null] )
This method sets up the authentication mechanism.
public void setVars( $requestOrResult )
This method sets the user ID and user name variables as part of the $request and $result objects.

Methods

__construct

ezcMvcAuthenticationFilter __construct( [ezcMvcAuthenticationFilterOptions $options = null] )
Constructs a new ezcMvcAuthenticationFilter object

Parameters

Name Type Description
$options ezcMvcAuthenticationFilterOptions  

checkUserExists

bool checkUserExists( string $username )
Checks whether a user exists in the database.
This method should be called from the "register" action to see if the requested user ID has already been registered or not.

Parameters

Name Type Description
$username string  

createUser

void createUser( string $username, string $password, $extraInfo )
Creates an entry in the user database table for $username and $password.
This method creates a user in the configured user table (through the options for this class). You can specify extra information as a key->value pair array as $extraInfo. This method does *not* check whether a user already exists.

Parameters

Name Type Description
$username string  
$password string  
$extraInfo array(string=>mixed)  

fetchUserName

string fetchUserName( )
Returns the username associated with the user ID as stored in the session.
This method could be a likely candidate to override as well, although it is as configurable as possible. If usernames are not stored in the database, this method needs to be overridden as well. The method's return value is used by the setVars() method to add user ID and user name to the session so that the application can use this data.

generatePassword

string generatePassword( string $username )
Returns a generated basic password depending on the $username.
This method is typically called from the "register" action after a user ID has been checked for existance.

Parameters

Name Type Description
$username string  

getOptions

Returns the currently set options

hashPassword

string hashPassword( string $password )
Returns the hashed version of the clear text password

Parameters

Name Type Description
$password string  

login

void login( $request, string $user, string $password )
Method to be called from the controller's login action to log a user in.

Parameters

Name Type Description
$request ezcMvcRequest  
$user string  
$password string  

logout

void logout( $request )
Method to be called from the controller's logout action to log a user out.

Parameters

Name Type Description
$request ezcMvcRequest  

processLoginRequired

void processLoginRequired( $res, array(string) $reasons, [array(string=>array(int=>string) $errorMap = null], ezcMvcResult $result )
Checks the status from the authentication run and adds the reasons as variable to the $result.
This method uses the information that is set by the runAuthRequiredFilter() filter to generate an user-readable text of the found $reasons and sets these as the variable ezcAuth_reasons in the $result. You can supply your own mapping from status codes to messages, but a default is provided. Please refer to the Authentication tutorial for information about status codes.

Parameters

Name Type Description
$result ezcMvcResult  
$reasons array(string)  
$errorMap array(string=>array(int=>string)  
$res ezcMvcResult  

returnLoginRedirect

ezcMvcInternalRedirect|ezcMvcResult returnLoginRedirect( $authentication, $request, string $redirUrl )
Returns either an internal or external redirect depending on whether the user authenticated succesfully.
This method is run from the "login" action just after login() has been called. It takes the $authentication object, the $request and the form provided $redirUrl. It redirects upon failure to the configured loginRequiredUri and upon succes to the provided $redirUrl. The redirection happens by returning an ezcMvcInternalRedirect or ezcMvcResult with a ezcMvcExternalRedirect status.

Parameters

Name Type Description
$authentication ezcAuthentication  
$request ezcMvcRequest  
$redirUrl string  

returnLogoutRedirect

ezcMvcResult returnLogoutRedirect( $request )
Returns an external redirect depending to the configured logoutUri.
This method is run from the "logout" action just after logout() has been called. It takes the $request object as parameter although this is not used by this default implementation. The method returns an ezcMvcRequest result with a ezcMvcExternalRedirect status to redirect to the configured logoutUri.

Parameters

Name Type Description
$request ezcMvcRequest  

runAuthCheckLoggedIn

void runAuthCheckLoggedIn( $request )
Sets up the authentication mechanism to be used for routes that do not require authentication.
This method is meant to be run from the runRequestFilters() method for the routes that do not require authentication or deal with logging in, logging out and registering users. It sets up the session so that the controller has access to the authentication data.

Parameters

Name Type Description
$request ezcMvcRequest  

runAuthRequiredFilter

void runAuthRequiredFilter( ezcMvcRequest $request )
Sets up the authentication mechanism to be used for routes that do require authentication.
This method is meant to be run from the runRequestFilters() method for the routes that do require an authenticated user. It sets up the session so that the controller has access to the authentication data. The method will return an internal redirect return that redirects to the configured loginRequiredUri. That Uri's controller and action needs to present the login form.

Parameters

Name Type Description
$request ezcMvcRequest  

setOptions

void setOptions( ezcMvcAuthenticationFilterOptions $options )
Sets a new options object

Parameters

Name Type Description
$options ezcMvcAuthenticationFilterOptions  

setupAuth

ezcAuthentication setupAuth( [string $user = null], [string $password = null] )
This method sets up the authentication mechanism.
By default it uses database and session storage only. If you want to do more complex things, the best way would be to inherit from this class and override this method. It takes a user name and password, but those can be empty if your overridden class does not require them. This method will also be called with $user and $password being NULL in case the filter needs to check whether a user is already logged in. In this case, the session should be checked.

Parameters

Name Type Description
$user string  
$password string  

setVars

void setVars( ezcMvcRequest|ezcMvcResult $requestOrResult )
This method sets the user ID and user name variables as part of the $request and $result objects.
This method should be called by the application's runRequestFilters() and runResultFilters() methods to add authentication information to the request and/or result. The method also makes the authentication filter available to the controller actions so it is important that it is called in both filters, and preferably as the first method call.
The variable names that contain the user ID and user name can be configured through the $options object that is passed to the contructor.

Parameters

Name Type Description
$requestOrResult ezcMvcRequest|ezcMvcResult  

Last updated: Tue, 23 Mar 2010