Authenticating a request that includes authentication credentials is useful per se, but it is also important to support maintaining the authenticated identity without having to present the authentication credentials with each request.
HTTP is a stateless protocol, however, and techniques such as cookies and sessions have been developed in order to facilitate maintaining state across multiple requests in server-side web applications.
By default, Zend_Auth provides persistent storage of the
identity from a successful authentication attempt using the PHP
session. Upon a successful authentication attempt,
Zend_Auth::authenticate() stores the identity from the
authentication result into persistent storage. Unless configured otherwise,
Zend_Auth uses a storage class named
Zend_Auth_Storage_Session, which, in turn, uses
Zend_Session. A custom
class may instead be used by providing an object that implements
Zend_Auth_Storage_Interface to
Zend_Auth::setStorage().
Note
If automatic persistent storage of the identity is not appropriate for a
particular use case, then developers may forgot using the
Zend_Auth class altogether, instead using an adapter
class directly.
Example 55. Modifying the Session Namespace
Zend_Auth_Storage_Session uses a session namespace of
'Zend_Auth'. This namespace may be overridden by passing
a different value to the constructor of
Zend_Auth_Storage_Session, and this value is internally
passed along to the constructor of
Zend_Session_Namespace. This should occur before
authentication is attempted, since
Zend_Auth::authenticate() performs the automatic
storage of the identity.
<?php
// Save a reference to the Singleton instance of Zend_Auth
$auth = Zend_Auth::getInstance();
// Use 'someNamespace' instead of 'Zend_Auth'
$auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));
/**
* @todo Set up the auth adapter, $authAdapter
*/
// Authenticate, saving the result, and persisting the identity on
// success
$result = $auth->authenticate($authAdapter);
Sometimes developers may need to use a different identity storage mechanism than
that provided by Zend_Auth_Storage_Session. For such cases
developers may simply implement Zend_Auth_Storage_Interface
and supply an instance of the class to
Zend_Auth::setStorage().
Example 56. Using a Custom Storage Class
In order to use an identity persistence storage class other than
Zend_Auth_Storage_Session, a developer implements
Zend_Auth_Storage_Interface:
<?php
class MyStorage implements Zend_Auth_Storage_Interface
{
/**
* Returns true if and only if storage is empty
*
* @throws Zend_Auth_Storage_Exception If it is impossible to
* determine whether storage
* is empty
* @return boolean
*/
public function isEmpty()
{
/**
* @todo implementation
*/
}
/**
* Returns the contents of storage
*
* Behavior is undefined when storage is empty.
*
* @throws Zend_Auth_Storage_Exception If reading contents from
* storage is impossible
* @return mixed
*/
public function read()
{
/**
* @todo implementation
*/
}
/**
* Writes $contents to storage
*
* @param mixed $contents
* @throws Zend_Auth_Storage_Exception If writing $contents to
* storage is impossible
* @return void
*/
public function write($contents)
{
/**
* @todo implementation
*/
}
/**
* Clears contents from storage
*
* @throws Zend_Auth_Storage_Exception If clearing contents from
* storage is impossible
* @return void
*/
public function clear()
{
/**
* @todo implementation
*/
}
}
In order to use this custom storage class,
Zend_Auth::setStorage() is invoked before an
authentication query is attempted:
<?php
// Instruct Zend_Auth to use the custom storage class
Zend_Auth::getInstance()->setStorage(new MyStorage());
/**
* @todo Set up the auth adapter, $authAdapter
*/
// Authenticate, saving the result, and persisting the identity on
// success
$result = Zend_Auth::getInstance()->authenticate($authAdapter);