Zeta Components - high quality PHP components

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();
  4.  
  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 ( $status as $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();
  3.  
  4.  $credentials = new ezcAuthenticationPasswordCredentials( $user, $pass );
  5.  
  6.  $authenticated = false;
  7.  if ( !$session->isValid( $credentials ) )
  8.  {
  9.      // create the authentication object
  10.      $authentication = new ezcAuthentication( $credentials );
  11.      $authentication->session = $session;
  12.  
  13.      // create filters and add them to the authentication object
  14.      $authentication->addFilter( new ezcAuthenticationOpenidFilter() );
  15.  
  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.  }
  31.  
  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