## Apache Zeta Components Manual :: Docs For Class ezcAuthenticationSession

### Authentication::ezcAuthenticationSession

### Class ezcAuthenticationSession

Support for session authentication and saving of authentication information between requests.

Contains the methods:

- start - starts the session, calling the PHP function session_start()
- load - returns the information stored in the session key ezcAuth_id
- save - saves information in the session key ezcAuth_id and also saves the current timestamp in the session key ezcAuth_timestamp
- destroy - deletes the information stored in the session keys ezcAuth_id and ezcAuth_timestamp
- regenerateId - regenerates the PHPSESSID value

Example of use (combined with the Htpasswd filter):

1. // no headers should be sent before calling $session->start()
2. $session=new ezcAuthenticationSession ();
3. $session-> start ();
5. // retrieve the POST request information
6. $user= isset($_POST['user'])?$_POST['user']:$session-> load ();
7. $password= isset($_POST['password'])?$_POST['password']:null;
8. $credentials=new ezcAuthenticationPasswordCredentials ($user,$password);
9. $authentication=new ezcAuthentication ($credentials);
10. $authentication->session=$session;
11. $authentication->addFilter(new ezcAuthenticationHtpasswdFilter ('/etc/htpasswd') );
12. // add other filters if needed
13. if(!$authentication-> run () )
14. {
15. // authentication did not succeed, so inform the user
16. $status=$authentication->getStatus();
17. $err=array(
18. 'ezcAuthenticationHtpasswdFilter'=>array(
19. ezcAuthenticationHtpasswdFilter ::STATUS_USERNAME_INCORRECT=>'Incorrect username',
20. ezcAuthenticationHtpasswdFilter ::STATUS_PASSWORD_INCORRECT=>'Incorrect password'
21. ),
22. 'ezcAuthenticationSession'=>array(
23. ezcAuthenticationSession ::STATUS_EMPTY=>'',
24. ezcAuthenticationSession ::STATUS_EXPIRED=>'Session expired'
25. )
26. );
27. foreach($statusas$line)
28. {
29. list($key,$value)=each ($line);
30. echo$err[$key][$value]."\n";
31. }
32. }
33. else
34. {
35. // authentication succeeded, so allow the user to see his content
36. }

See ezcAuthenticationSessionOptions for options you can set to session objects.

Source for this file: /Authentication/src/session/authentication_session.php

Version: | //autogen//

### Constants

`STATUS_EMPTY = 1` | The session is empty; normal behaviour is to continue with the other filters.
`STATUS_EXPIRED = 2` | The session expired; normal behaviour is to regenerate the session ID.
`STATUS_OK = 0` | Successful authentication; normal behaviour is to skip the other filters. This should be the same value as ezcAuthenticationFilter::STATUS_OK.

### Member Variables

protected ezcAuthenticationFilterOptions | `$options` Options for authentication filters.

### Method Summary

public ezcAuthenticationSession | `__construct( [ $options = null] )` Creates a new object of this class.
public void | `destroy( )` Removes the variables used by this class from the session variables.
public ezcAuthenticationSessionOptions | `getOptions( )` Returns the options of this class.
public bool | `isValid( $credentials )` Runs through the session and returns true if the session is correct.
public string | `load( )` Loads the authenticated username from the session or null if it doesn't exist.
public void | `regenerateId( )` Regenerates the session ID.
public int | `run( $credentials )` Runs through the session and returns a status code when finished.
public void | `save( $data )` Saves the authenticated username and the current timestamp in the session variables.
public void | `setOptions( $options )` Sets the options of this class to $options.
public void | `start( )` Starts the session.

### Methods

#### __construct

ezcAuthenticationSession __construct( [ezcAuthenticationSessionOptions $options = null] )

Creates a new object of this class.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$options` | ezcAuthenticationSessionOptions | Options for this class

#### destroy

void destroy( )

Removes the variables used by this class from the session variables.

#### getOptions

ezcAuthenticationSessionOptions getOptions( )

Returns the options of this class.

#### isValid

bool isValid( ezcAuthenticationCredentials $credentials )

Runs through the session and returns true if the session is correct.

When using the session, it is often desirable to take advantage of the fact that the authenticated state of the user is kept in the session and not create and initialize the other filters (which might slow things down on every request).

The application can be structured like this:

1. $session=new ezcAuthenticationSession ();
2. $session-> start ();
4. $credentials=new ezcAuthenticationPasswordCredentials ($user,$pass);
6. $authenticated=false;
7. if(!$session-> isValid ($credentials) )
8. {
9. // create the authentication object
10. $authentication=new ezcAuthentication ($credentials);
11. $authentication->session=$session;
13. // create filters and add them to the authentication object
14. $authentication->addFilter(new ezcAuthenticationOpenidFilter () );
16. // run the authentication object
17. if(!$authentication-> run () )
18. {
19. $status=$authentication->getStatus();
20. // build an error message based on $status
21. }
22. else
23. {
24. $authenticated=true;
25. }
26. }
27. else
28. {
29. $authenticated=true;
30. }
32. if($authenticated)
33. {
34. // the authentication succeeded and the user can see his content
35. }
36. else
37. {
38. // inform the user that the authentication failed (with the error
39. // message that was created earlier)
40. }

In this way, the creation and initialization of the authentication filters is not performed if the credentials are stored in the session.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$credentials` | ezcAuthenticationCredentials | Authentication credentials

#### load

string load( )

Loads the authenticated username from the session or null if it doesn't exist.

#### regenerateId

void regenerateId( )

Regenerates the session ID.

#### run

int run( ezcAuthenticationCredentials $credentials )

Runs through the session and returns a status code when finished.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$credentials` | ezcAuthenticationCredentials | Authentication credentials

#### save

void save( string $data )

Saves the authenticated username and the current timestamp in the session variables.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$data` | string | Information to save in the session, usually username

#### setOptions

void setOptions( ezcAuthenticationSessionOptions $options )

Sets the options of this class to $options.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$options` | ezcAuthenticationSessionOptions | Options for this class

#### start

void start( )

Starts the session.

This function must be called before sending any headers to the client.

Documentation generated by phpDocumentor 1.4.3