repo_zf1Php7/documentation/manual/ja/module_specs/Zend_Controller-Request.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15719 -->
<sect1 id="zend.controller.request">
    <title>リクエストオブジェクト</title>
    <sect2 id="zend.controller.request.introduction">
        <title>導入</title>
        <para>
            リクエストオブジェクトとは <classname>Zend_Controller_Front</classname> とルータ、
            ディスパッチャそしてコントローラクラスの間でやり取りされる単純なバリューオブジェクトです。
            これはコントローラ、アクションそして環境 (HTTP、CLI、PHP-GTK など)
            に応じたその他のパラメータの内容をまとめたものです。
        </para>

        <itemizedlist>
            <listitem><para>
                モジュール名にアクセスするには
                <code>getModuleName()</code> および
                <code>setModuleName()</code> を使用します。
            </para></listitem>

            <listitem><para>
                コントローラ名にアクセスするには
                <code>getControllerName()</code> および
                <code>setControllerName()</code> を使用します。
            </para></listitem>

            <listitem><para>
                コントローラ内でコールするアクションの名前にアクセスするには
                <code>getActionName()</code> および
                <code>setActionName()</code> を使用します。
            </para></listitem>

            <listitem><para>
                アクションからアクセスできるパラメータは
                キー/値 の組み合わせの連想配列となります。これらを取得するには
                <code>getParams()</code> を、そして設定するには
                <code>setParams()</code> を使用します。各パラメータを個別に扱うには
                <code>getParam()</code> および <code>setParam()</code> を使用します。
            </para></listitem>
        </itemizedlist>

        <para>
            リクエストの型によっては、その他のメソッドが使用できることもあります。
            たとえば、デフォルトのリクエストで使用する
            <classname>Zend_Controller_Request_Http</classname> の場合は、
            リクエストされた URI やパス情報、
            <varname>$_GET</varname> パラメータや <varname>$_POST</varname>
            パラメータを取得するメソッドが使用可能となります。
        </para>

        <para>
            リクエストオブジェクトはフロントコントローラに渡されます。
            もしリクエストオブジェクトがなかった場合は、
            ディスパッチ処理の最初 (ルーティングが発生する前)
            にインスタンスが作成されます。これは、
            ディスパッチチェインのすべてのオブジェクトに渡されていきます。
        </para>

        <para>
            さらに、リクエストオブジェクトはテストの際にも有用です。
            開発者がリクエストを作成し、コントローラやアクション、
            パラメータや URI などを指定してそれをフロントコントローラに渡すことで、
            アプリケーションの流れをテストすることができます。
            <link linkend="zend.controller.response">レスポンスオブジェクト</link>
            と組み合わせて使用すると、
            MVC アプリケーションの精密で正確な単体テストが可能となります。
        </para>
    </sect2>

    <sect2 id="zend.controller.request.http">
        <title>HTTP リクエスト</title>

        <sect3 id="zend.controller.request.http.dataacess">
            <title>リクエストデータへのアクセス</title>

            <para>
                <classname>Zend_Controller_Request_Http</classname> は、関連する値へのアクセスをカプセル化します。
                たとえばコントローラやアクションルータの変数のキー名や値、
                URI からパースした追加のパラメータの値などにアクセスできます。
                <classname>Zend_Controller_Request_Http</classname> のプロキシとして動作することで、
                スーパーグローバルの値にパブリックメンバとしてアクセスしたり、
                現在のベース URL やリクエスト URI を管理することもできます。
                スーパーグローバルの値はリクエストオブジェクトに設定することはできません。
                そのかわりに setParam/getParam メソッドを使用して、
                パラメータを設定あるいは取得します。
            </para>

            <note>
                <title>スーバーグローバルデータ</title>
                <para>
                    <classname>Zend_Controller_Request_Http</classname> のパブリックプロパティを使用して
                    スーパーグローバルデータにアクセスする際に注意すべき点は、
                    プロパティ名 (スーバーグローバル配列のキー)
                    は以下の優先順位でマッチするということです。
                    1. GET, 2. POST, 3. COOKIE, 4. SERVER, 5. ENV.
                </para>
            </note>

            <para>
                特定のスーパーグローバルにアクセスするには、
                パブリックメソッドを使用する方法もあります。たとえば、
                <varname>$_POST['user']</varname> の値を取得するには、リクエストオブジェクト上で
                <code>getPost('user')</code> をコールします。同様に、
                <varname>$_GET</varname> 要素の場合は <code>getQuery()</code>、
                リクエストヘッダの場合は <code>getHeader()</code>
                を使用します。
            </para>

            <note>
                <title>GET および POST データ</title>
                <para>
                    リクエストオブジェクトのデータを扱う際には注意しましょう。
                    これらのデータは、一切フィルタリングを行っていません。
                    ルータやディスパッチャのほうで適切な検証とフィルタリングを行うので、
                    リクエストオブジェクト内のデータはそのままにしておきましょう。
                </para>
            </note>

            <note>
                <title>生の POST データの取得</title>

                <para>
                    1.5.0 以降では、生の投稿データを
                    <code>getRawBody()</code> メソッドで取得することができます。
                    このメソッドは、データが送信されていない場合は false を返します。
                    送信されている場合は、投稿内容の本文全体を返します。
                </para>

                <para>
                    これは、RESTful な MVC
                    アプリケーションを開発するにあたって非常に有用です。
                </para>
            </note>

            <para>
                ユーザパラメータをリクエストオブジェクトに設定するには
                <code>setParam()</code> を、後でそれを取得するには
                <code>getParam()</code> を使用します。
                ルータは、リクエスト URI にマッチしたパラメータを
                リクエストオブジェクトに設定する際にこの機能を使用します。
            </para>

            <note>
                <title>getParam() でのユーザパラメータ以外の取得</title>

                <para>
                    <code>getParam()</code> は、実際にはユーザパラメータ以外のところからも情報を取得しています。
                    優先順位の高い順に並べると、まず最初は <code>setParam()</code>
                    で設定したパラメータ、それから <code>GET</code> パラメータ、
                    <code>POST</code> パラメータの順になります。
                    このメソッドを使用する際には、この点に注意しましょう。
                </para>

                <para>
                    <code>setParam()</code> で設定したパラメータからだけ取得したい場合は、
                    <code>getUserParam()</code> を使用します。
                </para>

                <para>
                    さらに、1.5.0 以降では
                    どのパラメータから検索するかを制限することができます。
                    <code>setParamSources()</code> に空の配列あるいは
                    値 '_GET' や '_POST' を含む配列を指定して使用します
                    (デフォルトでは両方が指定されています)。'_GET'
                    からのみに制限したい場合は
                    <code>setParamSources(array('_GET'))</code> とします。
                </para>
            </note>

            <note>
                <title>Apache のおかしな挙動</title>
                <para>
                    Apache の 404 ハンドラを使用して
                    リクエストをフロントコントローラに渡したり、
                    PT フラグを rewrite ルールで使用したりする場合は、
                    必要な URI 情報が含まれるのが
                    <varname>$_SERVER['REQUEST_URI']</varname>
                    ではなく <varname>$_SERVER['REDIRECT_URL']</varname>
                    であることに注意しましょう。
                    この設定を使用して無効なルーティングを取得したい場合は、
                    デフォルトの Http クラスではなく
                    <classname>Zend_Controller_Request_Apache404</classname>
                    クラスを使用してリクエストオブジェクトを作成しなければなりません。
                </para>

                <programlisting language="php"><![CDATA[
$request = new Zend_Controller_Request_Apache404();
$front->setRequest($request);
]]></programlisting>

                <para>
                    このクラスは
                    <classname>Zend_Controller_Request_Http</classname>
                    クラスを継承したもので、リクエスト URI
                    を自動で検出できるように変更しています。
                    これは、単純にもとのクラスと差し替えて使用できます。
                </para>
            </note>
        </sect3>

        <sect3 id="zend.controller.request.http.baseurl">
            <title>ベース URL およびサブディレクトリ</title>

            <para>
                <classname>Zend_Controller_Request_Http</classname> は、
                サブディレクトリで <classname>Zend_Controller_Router_Rewrite</classname> を使用することができます。
                <classname>Zend_Controller_Request_Http</classname> は自動的にベース URL を検出し、
                それを適切に設定します。
            </para>

            <para>
                たとえば、<code>index.php</code> をウェブサーバのサブディレクトリ
                <code>/projects/myapp/index.php</code> においた場合は、ベース URL
                (rewrite base) は <code>/projects/myapp</code> にしなければなりません。
                マッチするルートを見つける前に、この文字列がパスの先頭から取り除かれます。
                これにより、すべてのルートに余計な文字を追加する必要がなくなります。
                ルート <code>'user/:username'</code> は、
                <code>http://localhost/projects/myapp/user/martel</code> および
                <code>http://example.com/user/martel</code> の両方にマッチするようになります。
            </para>

            <note>
                <title>URL の検出は大文字小文字を区別します</title>
                <para>
                    自動的なベース URL の検出処理は大文字小文字を区別します。そのため、
                    URL とファイルシステムのサブディレクトリ名が確実に一致する必要があります
                    (たとえ Windows マシンであっても同様です)。大文字小文字が一致しなかった場合は、
                    例外が発生します。
                </para>
            </note>

            <para>
                ベース URL の検出に失敗する場合は、
                <classname>Zend_Controller_Request_Http</classname> クラス、あるいは
                <classname>Zend_Controller_Front</classname> クラスの
                <code>setBaseUrl()</code> メソッドを使用して
                ベースパスを上書き指定することができます。
                一番簡単な方法は <classname>Zend_Controller_Front</classname> で設定することです。
                この設定はリクエストオブジェクトに引き継がれます。
                独自のベース URL を設定する例を示します。
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Zend_Controller_Front で独自のベース URL を指定することによるリクエストのディスパッチ
 */
$router     = new Zend_Controller_Router_Rewrite();
$controller = Zend_Controller_Front::getInstance();
$controller->setControllerDirectory('./application/controllers')
           ->setRouter($router)
           ->setBaseUrl('/projects/myapp'); // ベース URL を指定します!
$response   = $controller->dispatch();
]]></programlisting>

        </sect3>

        <sect3 id="zend.controller.request.http.method">
            <title>リクエストメソッドの判定</title>

            <para>
                <code>getMethod()</code> では、
                現在のリソースへのリクエストの際に使用した
                HTTP メソッドを判定することができます。
                さらに、指定した型のリクエストであったかどうかを判定するための
                メソッドも用意されています。
            </para>

            <itemizedlist>
                <listitem><para><code>isGet()</code></para></listitem>
                <listitem><para><code>isPost()</code></para></listitem>
                <listitem><para><code>isPut()</code></para></listitem>
                <listitem><para><code>isDelete()</code></para></listitem>
                <listitem><para><code>isHead()</code></para></listitem>
                <listitem><para><code>isOptions()</code></para></listitem>
            </itemizedlist>

            <para>
                これらの主な使用法は、RESTfult な
                MVC アーキテクチャを作成することです。
            </para>
        </sect3>

        <sect3 id="zend.controller.request.http.ajax">
            <title>AJAX リクエストの検出</title>

            <para>
                <classname>Zend_Controller_Request_Http</classname> には、
                AJAX リクエストを検出するための基本的なメソッド
                <code>isXmlHttpRequest()</code> が用意されています。
                このメソッドは、HTTP リクエストヘッダ
                <code>X-Requested-With</code> に
                'XMLHttpRequest' という値が設定されているかどうかを調べ、
                設定されている場合に true を返します。
            </para>

            <para>
                現時点では、次の JS ライブラリがデフォルトでこのヘッダを渡すようです。
            </para>

            <itemizedlist>
                <listitem><para>Prototype/Scriptaculous (その他
                        Prototype 系のライブラリ)</para></listitem>
                <listitem><para>Yahoo! UI Library</para></listitem>
                <listitem><para>jQuery</para></listitem>
                <listitem><para>MochiKit</para></listitem>
            </itemizedlist>

            <para>
                大半の AJAX ライブラリは、独自の HTTP リクエストヘッダを送信することができます。
                ご利用のライブラリがこのヘッダを送信していない場合は、
                自分でこのヘッダを追加することで
                <code>isXmlHttpRequest()</code> メソッドの動作を期待通りにすることができます。
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.controller.request.subclassing">
        <title>リクエストオブジェクトのサブクラスの作成</title>

        <para>
            すべてのリクエストオブジェクトクラスは、抽象クラス
            <classname>Zend_Controller_Request_Abstract</classname> を継承しています。
            このクラスでは、次のようなメソッドを定義しています。
        </para>

        <programlisting language="php"><![CDATA[
abstract class Zend_Controller_Request_Abstract
{
    /**
     * @return string
     */
    public function getControllerName();

    /**
     * @param string $value
     * @return self
     */
    public function setControllerName($value);

    /**
     * @return string
     */
    public function getActionName();

    /**
     * @param string $value
     * @return self
     */
    public function setActionName($value);

    /**
     * @return string
     */
    public function getControllerKey();

    /**
     * @param string $key
     * @return self
     */
    public function setControllerKey($key);

    /**
     * @return string
     */
    public function getActionKey();

    /**
     * @param string $key
     * @return self
     */
    public function setActionKey($key);

    /**
     * @param string $key
     * @return mixed
     */
    public function getParam($key);

    /**
     * @param string $key
     * @param mixed $value
     * @return self
     */
    public function setParam($key, $value);

    /**
     * @return array
     */
     public function getParams();

    /**
     * @param array $array
     * @return self
     */
    public function setParams(array $array);

    /**
     * @param boolean $flag
     * @return self
     */
    public function setDispatched($flag = true);

    /**
     * @return boolean
     */
    public function isDispatched();
}
]]></programlisting>

        <para>
            リクエストオブジェクトは、リクエスト環境のコンテナとなります。
            コントローラチェインが知っておくべきことは、
            コントローラやアクション、オプションパラメータ、ディスパッチ状況
            を取得したり設定したりする方法だけです。
            デフォルトでは、リクエストオブジェクトが
            コントローラおよびアクションを決定する際には
            キー controller あるいは action を使用します。
        </para>

        <para>
            このクラスかその派生クラスのいずれかを継承したクラスを作成することで、
            上で説明した作業を独自のものに変更したクラスを作成することができます。
            例としては、たとえば <link linkend="zend.controller.request.http">HTTP
            環境用</link> のクラスや CLI 環境用、PHP-GTK 環境用のクラスがあります。
        </para>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->