Un adaptador Zend_Auth es usado para autenticar en contra de un tipo particular de servicio de autenticación, como LDAP , RDBMS , o almacenamiento basado en ficheros. Diferentes adaptadores pueden tener opciones y compotamientos muy diferentes, pero algunas cosas básicas son comunes entre los adaptadores de autenticación. Por ejemplo, aceptar credenciales de autenticación (incluyendo una identidad supuesta), realizar consultas ante el servicio de autenticación, y regresar resultados, son comunes para los adaptadores Zend_Auth .

Cada clase adaptadora Zend_Auth implementa Zend_Auth_Adapter_Interface . Esta interface define un metodo, authenticate() , que la clase adaptadora debe implementar para realizar una peticion de autenticación. Cada clase adaptadora debe ser preparada antes de llamar a authenticate() . Esta preparación del adaptador incluye la creación de credenciales (p.ej. nombre de usuario y contraseña) y la definición de valores para opciones de configuración especificos del adaptador, como valores de coneccion a base de datos para un adaptador de tabla de base de datos.

El siguente ejemplo es un adaptador de autenticación que requiere que un nombre de usuario y contraseña sean especificados para la autenticación. Otros detalles, como la forma de realizar peticiones al servicio de autenticación, han sido omitídos por brevedad:

class MyAuthAdapter implements Zend_Auth_Adapter_Interface
{
    /**
     * Establece nombre de usuario y contraseña para autenticacón
     *
     * @return void
     */
    public function __construct($username, $password)
    {
        // ...
    }

    /**
     * Realiza un intento de autenticación
     *
     * @throws Zend_Auth_Adapter_Exception Si la autenticación no puede
     *                                     ser realizada
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
        // ...
    }
}

Como se ha indicado en su docblock, authenticate() debe regresar una instancia de Zend_Auth_Result (o de una clase derivada de Zend_Auth_Result ). Si por alguna razón es imposible realizar una petición de autenticación, authenticate() debería arrojar una excepción que se derive de Zend_Auth_Adapter_Exception .

Los adaptadores Zend_Auth regresan una instancia de Zend_Auth_Result con authenticate() para representar el resultado de un intento de autenticación. Los adaptadores llenan el objeto Zend_Auth_Result en cuanto se construye, así que los siguientes cuatro métodos proveen un grupo básico de operaciones "frente al usuario" que son comunes a los resultados de adaptadores Zend_Auth:

El desarrollador podría desear ramificar basado en el tipo de resultado de la autenticación a fin de realizar operaciones mas específicas. Algunas operaciones que los desarrolladores podrían encontrar útiles son: bloquear cuentas despues de varios intentos fallidos de ingresar una contraseña, marcar una dirección IP despues de que ha intentado muchas identidades no existentes, y porporcionar al usuario mensajes especificos resultados de la autenticación. Los siguientes codigos de resultado están disponibles:

Zend_Auth_Result::SUCCESS
Zend_Auth_Result::FAILURE
Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND
Zend_Auth_Result::FAILURE_IDENTITY_AMBIGUOUS
Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID
Zend_Auth_Result::FAILURE_UNCATEGORIZED

El siguiente ejemplo ilustra como un desarrollador podría ramificar basado en el código resultado:

// debtri de AuthController / loginAction
$result = $this->_auth->authenticate($adapter);

switch ($result->getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** realiza algo para identidad inexistente **/
        break;

    case Zend_Auth_Result::FAILURE_CREDENTIAL_INVALID:
        /** realiza algo para credencial invalida **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** realiza algo para autenticación exitosa **/
        break;

    default:
        /** realiza algo para otras fallas **/
        break;
}

Autenticar una petición que incluye credenciales de autenticación es util por sí mismo, pero también es importante el soportar mantener la identidad autenticada sin tener que presentar las credenciales de autenticación con cada petición.

HTTP es un protocolo sin estado, sin embargo, se han desarrollado técnicas como las cookies y sesiones a fin de facilitar mantener el estado a través de multiples peticiones en aplicaciones web del lado del servidor.

// Almacena una referencia a la instancia Singleton de Zend_Auth
$auth = Zend_Auth::getInstance();

// Usa 'unEspacionombre' en lugar de 'Zend_Auth'
$auth->setStorage(new Zend_Auth_Storage_Session('unEspacionombre'));

/**
 * @todo Set up the auth adapter, $authAdapter
 */

// Autenticar, almacenando el resultado, y persistiendo la identidad en
// suceso
$result = $auth->authenticate($authAdapter);

class MyStorage implements Zend_Auth_Storage_Interface
{
    /**
     * Regresa true si y solo si el almacenamiento esta vacio
     *
     * @arroja Zend_Auth_Storage_Exception Si es imposible
     *                                     determinar si el almacenamiento
     *                                     esta vacio
     * @regresa boleano
     */
    public function isEmpty()
    {
        /**
         * @por hacer implementación
         */
    }

    /**
     * Regresa el contenido del almacenamiento
     *
     * El comportamiento es indefinido cuando el almacenamiento esta vacio
     *
     * @arroja Zend_Auth_Storage_Exception Si leer contenido de
     *                                     almacenamiento es imposible
     * @regresa mixto
     */
    public function read()
    {
        /**
         * @por hacer implementación
         */
    }

    /**
     * Escribe $contents al almacenamiento
     *
     * @parametros mezclado $contents
     * @arroja Zend_Auth_Storage_Exception Si escribir $contents al
     *                                     almacenamiento es imposible
     * @regresa boleano
     */
    public function write($contents)
    {
        /**
         * @por hacer implementación
         */
    }

    /**
     * limpia contenidos del almacenamiento
     *
     * @arroja Zend_Auth_Storage_Exception Si limpiar contenidos del
     *                                     almacenamiento es imposible
     * @regresa void
     */
    public function clear()
    {
        /**
         * @por hacer implementación
         */
    }
}

// Instruye Zend_Auth para usar la clase de almacenamiento personalizada
Zend_Auth::getInstance()->setStorage(new MyStorage());

/**
 * @por hacer Configurar el adaptador de autenticación, $authAdapter
 */

// Autenticar, almacenando el resultado, y persistiendo la identidad
// si hay exito
$result = Zend_Auth::getInstance()->authenticate($authAdapter);

Hay dos formas provistas de usar adaptadores Zend_Auth :

El siguiente ejemplo ilustra como usar el adaptador :Zend_Auth : indirectamente, a través del uso de la clase Zend_Auth :

// Recibe una referencia a la instancia singleton de Zend_Auth
$auth = Zend_Auth::getInstance();

// Configura el adaptador de autenticación
$authAdapter = new MyAuthAdapter($username, $password);

// Intenta la autenticación, almacenando el resultado
$result = $auth->authenticate($authAdapter);

if (!$result->isValid()) {
    // Fautenticación fallida: imprime el por que
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Autenticación exitosa, la identidad ($username) es almacenada
    // en la sesión
    // $result->getIdentity() === $auth->getIdentity()
    // $result->getIdentity() === $username
}

Una vez que la autenticación ha sido intentada en una petición, como en el ejemplo anterior, es fácil verificar si existe una identidad autenticada exitosamente:

$auth = Zend_Auth::getInstance();
if ($auth->hasIdentity()) {
    // Existe la identidad; obtenla
    $identity = $auth->getIdentity();
}

Para remover una identidad del almacenamiento persistente, simplemente usa el metodo clearIdentity() method. Comunmente esto sería usado para implementar una operación "cerrar sesión" en la aplicación:

Zend_Auth::getInstance()->clearIdentity();

Cuando el uso automático de almacenamiento persistente es inapropiado para un caso en particular, el desarrollador podría simplemente omitir el uso de la clase Zend_Auth , usando una clase adaptadora directamente. El uso directo de una clase adaptadora implica configurar y preparar un objeto adaptador y despues llamar a su metodo authenticate() . Los detalles específicos del adaptador son discutidos en la documentación de cada adaptador. El siguiente ejemplo utiliza directamente MyAuthAdapter :

// Configura el adaptador de autenticación
$authAdapter = new MyAuthAdapter($username, $password);

// Intenta la autenticación, almacenando el resultado
$result = $authAdapter->authenticate();

if (!$result->isValid()) {
    // Autenticación fallida, imprime el porque
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // Autenticación exitosa
    // $result->getIdentity() === $username
}