Zend_Auth アダプタの使用目的は、 LDAP や RDBMS あるいはファイル のような特定の型の認証サービスに対する認証を行うことです。 アダプタによってそのオプションや挙動は大きくことなるでしょうが、 いくつかの基本処理は、あらゆる認証アダプタで共通となります。 たとえば認証条件 (いわゆる ID) を受け取り、 認証サービスに対する問い合わせを行い、 結果を返すという処理は、すべての Zend_Auth アダプタで共通です。

各 Zend_Auth アダプタクラスは、Zend_Auth_Adapter_Interface を実装しています。このインターフェイスで定義されているメソッドが authenticate() で、アダプタクラスは 認証クエリを実行するためにこれを実装する必要があります。 各アダプタクラスは、authenticate() をコールする前に準備を済ませておく必要があります。 つまり、アダプタ側で用意しなければならない機能としては 認証条件 (ユーザ名およびパスワードなど) の取得や アダプタ固有のオプションの設定 (データベースのテーブルを使用するアダプタならデータベースへの接続設定など) があるということです。

以下にあげるのは認証アダプタのサンプルで、 これはユーザ名とパスワードを受け取って認証を行います。 その他の詳細、例えば認証サービスへの実際の問い合わせなどは、 例を簡潔にするため省略しています。

<?php
require_once 'Zend/Auth/Adapter/Interface.php';

class MyAuthAdapter implements Zend_Auth_Adapter_Interface
{
    /**
     * 認証用のユーザ名とパスワードを設定します
     *
     * @return void
     */
    public function __construct($username, $password)
    {
        // ...
    }

    /**
     * 認証を試みます
     *
     * @throws Zend_Auth_Adapter_Exception が、認証処理をできなかった場合に発生します
     * @return Zend_Auth_Result
     */
    public function authenticate()
    {
        // ...
    }
}

docblock コメントで説明しているとおり、 authenticate() は Zend_Auth_Result (あるいは Zend_Auth_Result の派生クラス) のインスタンスを返す必要があります。何らかの理由で認証の問い合わせができなかった場合は、 authenticate() は Zend_Auth_Adapter_Exception から派生した例外をスローしなければなりません。

Zend_Auth アダプタは、authenticate() の結果として Zend_Auth_Result のインスタンスを返します。 これにより、認証を試みた結果を表します。アダプタのインスタンスを作成した際に Zend_Auth_Result オブジェクトが作成され、 以下の三つのメソッドで Zend_Auth アダプタの結果に対する共通の操作ができます。

認証の結果によって処理を分岐させ、より決め細やかな処理を行いたいこともあるでしょう。 有用な処理としては、たとえば間違ったパスワードを繰り返し入力したアカウントをロックしたり、 存在しない ID を何度も入力した IP アドレスに印をつけたり、 ユーザに対してよりわかりやすいメッセージを返したりといったことがあります。 次の結果コードが使用可能です。

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

次の例は、結果コードを処理する方法を示すものです。

<?php
// AuthController / loginAction の中の処理
$result = $this->_auth->authenticate($adapter);

switch ($result->getCode()) {

    case Zend_Auth_Result::FAILURE_IDENTITY_NOT_FOUND:
        /** ID が存在しない場合の処理 **/
        break;

    case Zend_Auth_Result::FAILURE_INVALID_CREDENTIAL:
        /** 認証に失敗した場合の処理 **/
        break;

    case Zend_Auth_Result::SUCCESS:
        /** 認証に成功した場合の処理 **/
        break;

    default:
        /** その他の原因で失敗した場合の処理 **/
        break;
}

認証情報 (パスワードなど) を含む認証を要求するのは便利なものですが、 リクエストごとにいちいち認証情報を引き回すのではなく、 認証済みの ID を保持し続けることも重要です。

HTTP はステートレスなプロトコルです。しかし、 クッキーやセッションといった技術によって、 サーバサイドのウェブアプリケーションでも 複数リクエスト間でステート (状態) を保持し続けられるようになりました。

3.1.3.1. PHP セッションにおけるデフォルトの持続性

デフォルトでは、Zend_Auth は、 認証に成功した際の ID 情報を PHP のセッションを使用して保存します。 認証に成功すると、Zend_Auth::authenticate() は認証結果を持続ストレージに保存します。何も指定しなければ、 Zend_Auth が使用するストレージクラスは Zend_Auth_Storage_Session となります。これは Zend_Session を使用しています。 独自のクラスを使用するには、Zend_Auth_Storage_Interface を実装したクラスのオブジェクトを Zend_Auth::setStorage() で設定します。

	注意
	もし ID が自動的に持続ストレージに保存されるのが気に入らない場合は、 Zend_Auth クラスをまるごと使用するのを控え、 アダプタクラスを直接使用します。

例 3.1. セッション名前空間の変更

Zend_Auth_Storage_Session は、セッション名前空間として 'Zend_Auth' を使用します。これを変更するには、別の値を Zend_Auth_Storage_Session のコンストラクタで指定します。 この値が、内部で Zend_Session_Namespace のコンストラクタに渡されます。これは認証を試みる前に行う必要があります。 なぜなら、Zend_Auth::authenticate() は ID を自動的に保存するからです。

<?php
// Zend_Auth のシングルトンインスタンスへの参照を保存します
require_once 'Zend/Auth.php';
$auth = Zend_Auth::getInstance();

// 'Zend_Auth' のかわりに 'someNamespace' を使用します
require_once 'Zend/Auth/Storage/Session.php';
$auth->setStorage(new Zend_Auth_Storage_Session('someNamespace'));

/**
 * @todo 認証アダプタ $authAdapter を設定します
 */

// 認証と結果の保存、そして成功時に ID を持続させます
$result = $auth->authenticate($authAdapter);

<?php
require_once 'Zend/Auth/Storage/Interface.php';

class MyStorage implements Zend_Auth_Storage_Interface
{
    /**
     * ストレージが空の場合にのみ true を返す
     *
     * @throws Zend_Auth_Storage_Exception 空かどうか判断できないとき
     * @return boolean
     */
    public function isEmpty()
    {
        /**
         * @todo 実装が必要
         */
    }

    /**
     * ストレージの中身を返す
     *
     * ストレージが空の場合に挙動は未定義
     *
     * @throws Zend_Auth_Storage_Exception ストレージの中身を読み込めない場合
     * @return mixed
     */
    public function read()
    {
        /**
         * @todo 実装が必要
         */
    }

    /**
     * $contents をストレージに書き込む
     *
     * @param  mixed $contents
     * @throws Zend_Auth_Storage_Exception $contents をストレージに書き込めない場合
     * @return void
     */
    public function write($contents)
    {
        /**
         * @todo 実装が必要
         */
    }

    /**
     * ストレージの中身を消去する
     *
     * @throws Zend_Auth_Storage_Exception ストレージの中身を消去できない場合
     * @return void
     */
    public function clear()
    {
        /**
         * @todo 実装が必要
         */
    }

}

<?php
// Zend_Auth に、独自のストレージクラスを使うよう指示します
Zend_Auth::getInstance()->setStorage(new MyStorage());

/**
 * @todo 認証アダプタ $authAdapter を設定します
 */

// 認証と結果の保存、そして成功時に ID を持続させます
$result = Zend_Auth::getInstance()->authenticate($authAdapter);

Zend_Auth の使用法には、次の二通りがあります。

次の例は、Zend_Auth アダプタを間接的に Zend_Auth クラスから使用するものです。

<?php
// Zend_Auth のシングルトンインスタンスへの参照を取得します
require_once 'Zend/Auth.php';
$auth = Zend_Auth::getInstance();

// 認証アダプタを設定します
$authAdapter = new MyAuthAdapter($username, $password);

// 認証を試み、その結果を取得します
$result = $auth->authenticate($authAdapter);

if (!$result->isValid()) {
    // 認証に失敗したので、原因を表示します
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // 認証に成功しました。ID ($username) がセッションに保存されます
    // $result->getIdentity() === $auth->getIdentity()
    // $result->getIdentity() === $username
}

上の例においてリクエスト内で認証が行われると、 認証に成功した際にその ID を取得するのは簡単なことです。

<?php
$auth = Zend_Auth::getInstance();
if ($auth->hasIdentity()) {
    // ID があるのでそれを取得します
    $identity = $auth->getIdentity();
}

永続ストレージから認証 ID を削除するには、単純に clearIdentity() メソッドを使用します。 これは、アプリケーションの "ログアウト" 処理を実装するためのものです。

<?php
Zend_Auth::getInstance()->clearIdentity();

自動的に永続ストレージが用いられるのがまずい場合もあるでしょう。 そんな場合は、Zend_Auth クラスをバイパスして アダプタクラスを直接使用します。 アダプタクラスを直接使用するとは、アダプタオブジェクトの設定と準備を行い、 その authenticate() メソッドをコールするということです。 アダプタ固有の詳細情報については、各アダプタのドキュメントで説明します。 以下の例は、MyAuthAdapter を直接使用するものです。

<?php
// 認証アダプタを設定します
$authAdapter = new MyAuthAdapter($username, $password);

// 認証を試み、その結果を取得します
$result = $authAdapter->authenticate();

if (!$result->isValid()) {
    // 認証に失敗したので、原因を表示します
    foreach ($result->getMessages() as $message) {
        echo "$message\n";
    }
} else {
    // 認証に成功しました
    // $result->getIdentity() === $username
}