Apache Zeta Components Manual :: File Source for authentication_session.php
Source for file authentication_session.php
Documentation is available at authentication_session.php
* File containing the ezcAuthenticationSession class.
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
* @package Authentication
* Support for session authentication and saving of authentication information
* - 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
* - regenerateId - regenerates the PHPSESSID value
* Example of use (combined with the Htpasswd filter):
* // no headers should be sent before calling $session->start()
* $session = new ezcAuthenticationSession();
* // retrieve the POST request information
* $user = isset( $_POST['user'] ) ? $_POST['user'] : $session->load();
* $password = isset( $_POST['password'] ) ? $_POST['password'] : null;
* $credentials = new ezcAuthenticationPasswordCredentials( $user, $password );
* $authentication = new ezcAuthentication( $credentials );
* $authentication->session = $session;
* $authentication->addFilter( new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd' ) );
* // add other filters if needed
* if ( !$authentication->run() )
* // authentication did not succeed, so inform the user
* $status = $authentication->getStatus();
* 'ezcAuthenticationHtpasswdFilter' => array(
* ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
* ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
* 'ezcAuthenticationSession' => array(
* ezcAuthenticationSession::STATUS_EMPTY => '',
* ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
* foreach ( $status as $line )
* list( $key, $value ) = each( $line );
* echo $err[$key][$value] . "\n";
* // authentication succeeded, so allow the user to see his content
* See {@link ezcAuthenticationSessionOptions} for options you can set to
* @package Authentication
* Successful authentication; normal behaviour is to skip the other filters.
* This should be the same value as ezcAuthenticationFilter::STATUS_OK.
* The session is empty; normal behaviour is to continue with the other filters.
* The session expired; normal behaviour is to regenerate the session ID.
const STATUS_EXPIRED =
2;
* Options for authentication filters.
* @var ezcAuthenticationFilterOptions
* Creates a new object of this class.
* @param ezcAuthenticationSessionOptions $options Options for this class
public function __construct( ezcAuthenticationSessionOptions $options =
null )
* Runs through the session and returns a status code when finished.
* @param ezcAuthenticationCredentials $credentials Authentication credentials
public function run( $credentials )
if ( isset
( $_SESSION[$this->options->timestampKey] ) &&
return self::STATUS_EXPIRED;
if ( $this->load() !==
null )
return self::STATUS_EMPTY;
* 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:
* $session = new ezcAuthenticationSession();
* $credentials = new ezcAuthenticationPasswordCredentials( $user, $pass );
* $authenticated = false;
* if ( !$session->isValid( $credentials ) )
* // create the authentication object
* $authentication = new ezcAuthentication( $credentials );
* $authentication->session = $session;
* // create filters and add them to the authentication object
* $authentication->addFilter( new ezcAuthenticationOpenidFilter() );
* // run the authentication object
* if ( !$authentication->run() )
* $status = $authentication->getStatus();
* // build an error message based on $status
* // the authentication succeeded and the user can see his content
* // inform the user that the authentication failed (with the error
* // message that was created earlier)
* In this way, the creation and initialization of the authentication
* filters is not performed if the credentials are stored in the session.
* @param ezcAuthenticationCredentials $credentials Authentication credentials
public function isValid( $credentials )
return ( $this->run( $credentials ) ===
self::STATUS_OK );
* This function must be called before sending any headers to the client.
* Loads the authenticated username from the session or null if it doesn't exist.
return isset
( $_SESSION[$this->options->idKey] ) ?
$_SESSION[$this->options->idKey] :
* Saves the authenticated username and the current timestamp in the session
* @param string $data Information to save in the session, usually username
public function save( $data )
$_SESSION[$this->options->idKey] =
$data;
* Removes the variables used by this class from the session variables.
unset
( $_SESSION[$this->options->idKey] );
unset
( $_SESSION[$this->options->timestampKey] );
* Regenerates the session ID.
// ???? seems that PHPSESSID is not regenerated if session is destroyed first????
* Sets the options of this class to $options.
* @param ezcAuthenticationSessionOptions $options Options for this class
public function setOptions( ezcAuthenticationSessionOptions $options )
* Returns the options of this class.
* @return ezcAuthenticationSessionOptions