| blob | c3935ec3fc38507a3202d918a6d09781c357fd75 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <!-- EN-Revision: 20765 -->
4 <sect1 id="zend.controller.request">
5 <title>リクエストオブジェクト</title>
6 <sect2 id="zend.controller.request.introduction">
7 <title>導入</title>
8 <para>
9 リクエストオブジェクトとは <classname>Zend_Controller_Front</classname> とルータ、
10 ディスパッチャそしてコントローラクラスの間でやり取りされる単純なバリューオブジェクトです。
11 これはコントローラ、アクションそして環境 (<acronym>HTTP</acronym>、<acronym>CLI</acronym>、<acronym>PHP</acronym>-GTK など)
12 に応じたその他のパラメータの内容をまとめたものです。
13 </para>
15 <itemizedlist>
16 <listitem><para>
17 モジュール名にアクセスするには
18 <methodname>getModuleName()</methodname> および
19 <methodname>setModuleName()</methodname> を使用します。
20 </para></listitem>
22 <listitem><para>
23 コントローラ名にアクセスするには
24 <methodname>getControllerName()</methodname> および
25 <methodname>setControllerName()</methodname> を使用します。
26 </para></listitem>
28 <listitem><para>
29 コントローラ内でコールするアクションの名前にアクセスするには
30 <methodname>getActionName()</methodname> および
31 <methodname>setActionName()</methodname> を使用します。
32 </para></listitem>
34 <listitem><para>
35 アクションからアクセスできるパラメータは
36 キー/値 の組み合わせの連想配列となります。これらを取得するには
37 <methodname>getParams()</methodname> を、そして設定するには
38 <methodname>setParams()</methodname> を使用します。各パラメータを個別に扱うには
39 <methodname>getParam()</methodname> および <methodname>setParam()</methodname> を使用します。
40 </para></listitem>
41 </itemizedlist>
43 <para>
44 リクエストの型によっては、その他のメソッドが使用できることもあります。
45 たとえば、デフォルトのリクエストで使用する
46 <classname>Zend_Controller_Request_Http</classname> の場合は、
47 リクエストされた <acronym>URI</acronym> やパス情報、
48 <varname>$_GET</varname> パラメータや <varname>$_POST</varname>
49 パラメータを取得するメソッドが使用可能となります。
50 </para>
52 <para>
53 リクエストオブジェクトはフロントコントローラに渡されます。
54 もしリクエストオブジェクトがなかった場合は、
55 ディスパッチ処理の最初 (ルーティングが発生する前)
56 にインスタンスが作成されます。これは、
57 ディスパッチチェインのすべてのオブジェクトに渡されていきます。
58 </para>
60 <para>
61 さらに、リクエストオブジェクトはテストの際にも有用です。
62 開発者がリクエストを作成し、コントローラやアクション、
63 パラメータや <acronym>URI</acronym> などを指定してそれをフロントコントローラに渡すことで、
64 アプリケーションの流れをテストできます。
65 <link linkend="zend.controller.response">レスポンスオブジェクト</link>
66 と組み合わせて使用すると、
67 <acronym>MVC</acronym> アプリケーションの精密で正確な単体テストが可能となります。
68 </para>
69 </sect2>
71 <sect2 id="zend.controller.request.http">
72 <title>HTTP リクエスト</title>
74 <sect3 id="zend.controller.request.http.dataacess">
75 <title>リクエストデータへのアクセス</title>
77 <para>
78 <classname>Zend_Controller_Request_Http</classname> は、関連する値へのアクセスをカプセル化します。
79 たとえばコントローラやアクションルータの変数のキー名や値、
80 <acronym>URI</acronym> からパースした追加のパラメータの値などにアクセスできます。
81 <classname>Zend_Controller_Request_Http</classname> のプロキシとして動作することで、
82 スーパーグローバルの値にパブリックメンバとしてアクセスしたり、
83 現在のベース <acronym>URL</acronym> やリクエスト <acronym>URI</acronym> を管理することもできます。
84 スーパーグローバルの値はリクエストオブジェクトに設定することはできません。
85 そのかわりに <methodname>setParam()</methodname> および <methodname>getParam()</methodname> メソッドを使用して、
86 パラメータを設定あるいは取得します。
87 </para>
89 <note>
90 <title>スーバーグローバルデータ</title>
91 <para>
92 <classname>Zend_Controller_Request_Http</classname> のパブリックプロパティを使用して
93 スーパーグローバルデータにアクセスする際に注意すべき点は、
94 プロパティ名 (スーバーグローバル配列のキー)
95 は以下の優先順位でマッチするということです。
96 1. <constant>GET</constant>, 2. <constant>POST</constant>, 3. <constant>COOKIE</constant>,
97 4. <constant>SERVER</constant>, 5. <constant>ENV</constant>.
98 </para>
99 </note>
101 <para>
102 特定のスーパーグローバルにアクセスするには、
103 パブリックメソッドを使用する方法もあります。たとえば、
104 <varname>$_POST['user']</varname> の値を取得するには、リクエストオブジェクト上で
105 <methodname>getPost('user')</methodname> をコールします。同様に、
106 <varname>$_GET</varname> 要素の場合は <methodname>getQuery()</methodname>、
107 リクエストヘッダの場合は <methodname>getHeader()</methodname>
108 を使用します。
109 </para>
111 <note>
112 <title>GET および POST データ</title>
113 <para>
114 リクエストオブジェクトのデータを扱う際には注意しましょう。
115 これらのデータは、一切フィルタリングを行っていません。
116 ルータやディスパッチャのほうで適切な検証とフィルタリングを行うので、
117 リクエストオブジェクト内のデータはそのままにしておきましょう。
118 </para>
119 </note>
121 <note>
122 <title>生の POST データの取得</title>
124 <para>
125 1.5.0 以降では、生の投稿データを
126 <methodname>getRawBody()</methodname> メソッドで取得できます。
127 このメソッドは、データが送信されていない場合は <constant>FALSE</constant> を返します。
128 送信されている場合は、投稿内容の本文全体を返します。
129 </para>
131 <para>
132 これは、RESTful な <acronym>MVC</acronym>
133 アプリケーションを開発するにあたって非常に有用です。
134 </para>
135 </note>
137 <para>
138 ユーザパラメータをリクエストオブジェクトに設定するには
139 <methodname>setParam()</methodname> を、後でそれを取得するには
140 <methodname>getParam()</methodname> を使用します。
141 ルータは、リクエスト <acronym>URI</acronym> にマッチしたパラメータを
142 リクエストオブジェクトに設定する際にこの機能を使用します。
143 </para>
145 <note>
146 <title>getParam() でのユーザパラメータ以外の取得</title>
148 <para>
149 <methodname>getParam()</methodname> は、実際にはユーザパラメータ以外のところからも情報を取得しています。
150 優先順位の高い順に並べると、まず最初は <methodname>setParam()</methodname>
151 で設定したパラメータ、それから <constant>GET</constant> パラメータ、
152 <constant>POST</constant> パラメータの順になります。
153 このメソッドを使用する際には、この点に注意しましょう。
154 </para>
156 <para>
157 <methodname>setParam()</methodname> で設定したパラメータからだけ取得したい場合は、
158 <methodname>getUserParam()</methodname> を使用します。
159 </para>
161 <para>
162 さらに、1.5.0 以降では
163 どのパラメータから検索するかを制限できます。
164 <methodname>setParamSources()</methodname> に空の配列あるいは
165 値 '_GET' や '_POST' を含む配列を指定して使用します
166 (デフォルトでは両方が指定されています)。'_GET'
167 からのみに制限したい場合は
168 <methodname>setParamSources(array('_GET'))</methodname> とします。
169 </para>
170 </note>
172 <note>
173 <title>Apache のおかしな挙動</title>
174 <para>
175 Apache の 404 ハンドラを使用して
176 リクエストをフロントコントローラに渡したり、
177 PT フラグを rewrite ルールで使用したりする場合は、
178 必要な <acronym>URI</acronym> 情報が含まれるのが
179 <varname>$_SERVER['REQUEST_URI']</varname>
180 ではなく <varname>$_SERVER['REDIRECT_URL']</varname>
181 であることに注意しましょう。
182 この設定を使用して無効なルーティングを取得したい場合は、
183 デフォルトの Http クラスではなく
184 <classname>Zend_Controller_Request_Apache404</classname>
185 クラスを使用してリクエストオブジェクトを作成しなければなりません。
186 </para>
188 <programlisting language="php"><![CDATA[
189 $request = new Zend_Controller_Request_Apache404();
190 $front->setRequest($request);
191 ]]></programlisting>
193 <para>
194 このクラスは
195 <classname>Zend_Controller_Request_Http</classname>
196 クラスを継承したもので、リクエスト <acronym>URI</acronym>
197 を自動で検出できるように変更しています。
198 これは、単純にもとのクラスと差し替えて使用できます。
199 </para>
200 </note>
201 </sect3>
203 <sect3 id="zend.controller.request.http.baseurl">
204 <title>ベース URL およびサブディレクトリ</title>
206 <para>
207 <classname>Zend_Controller_Request_Http</classname> は、
208 サブディレクトリで <classname>Zend_Controller_Router_Rewrite</classname> を使用できます。
209 <classname>Zend_Controller_Request_Http</classname> は自動的にベース <acronym>URL</acronym> を検出し、
210 それを適切に設定します。
211 </para>
213 <para>
214 たとえば、<filename>index.php</filename> をウェブサーバのサブディレクトリ
215 <filename>/projects/myapp/index.php</filename> においた場合は、ベース <acronym>URL</acronym>
216 (rewrite base) は <filename>/projects/myapp</filename> にしなければなりません。
217 マッチするルートを見つける前に、この文字列がパスの先頭から取り除かれます。
218 これにより、すべてのルートに余計な文字を追加する必要がなくなります。
219 ルート <command>'user/:username'</command> は、
220 <filename>http://localhost/projects/myapp/user/martel</filename> および
221 <filename>http://example.com/user/martel</filename> の両方にマッチするようになります。
222 </para>
224 <note>
225 <title>URL の検出は大文字小文字を区別します</title>
226 <para>
227 自動的なベース <acronym>URL</acronym> の検出処理は大文字小文字を区別します。そのため、
228 <acronym>URL</acronym> とファイルシステムのサブディレクトリ名が確実に一致する必要があります
229 (たとえ Windows マシンであっても同様です)。大文字小文字が一致しなかった場合は、
230 例外が発生します。
231 </para>
232 </note>
234 <para>
235 ベース <acronym>URL</acronym> の検出に失敗する場合は、
236 <classname>Zend_Controller_Request_Http</classname> クラス、あるいは
237 <classname>Zend_Controller_Front</classname> クラスの
238 <methodname>setBaseUrl()</methodname> メソッドを使用して
239 ベースパスを上書き指定できます。
240 一番簡単な方法は <classname>Zend_Controller_Front</classname> で設定することです。
241 この設定はリクエストオブジェクトに引き継がれます。
242 独自のベース <acronym>URL</acronym> を設定する例を示します。
243 </para>
245 <programlisting language="php"><![CDATA[
246 /**
247 * Zend_Controller_Front で独自のベース URL を指定することによるリクエストのディスパッチ
248 */
249 $router = new Zend_Controller_Router_Rewrite();
250 $controller = Zend_Controller_Front::getInstance();
251 $controller->setControllerDirectory('./application/controllers')
252 ->setRouter($router)
253 ->setBaseUrl('/projects/myapp'); // ベース URL を指定します!
254 $response = $controller->dispatch();
255 ]]></programlisting>
257 </sect3>
259 <sect3 id="zend.controller.request.http.method">
260 <title>リクエストメソッドの判定</title>
262 <para>
263 <methodname>getMethod()</methodname> では、
264 現在のリソースへのリクエストの際に使用した
265 <acronym>HTTP</acronym> メソッドを判定できます。
266 さらに、指定した型のリクエストであったかどうかを判定するための
267 メソッドも用意されています。
268 </para>
270 <itemizedlist>
271 <listitem><para><methodname>isGet()</methodname></para></listitem>
272 <listitem><para><methodname>isPost()</methodname></para></listitem>
273 <listitem><para><methodname>isPut()</methodname></para></listitem>
274 <listitem><para><methodname>isDelete()</methodname></para></listitem>
275 <listitem><para><methodname>isHead()</methodname></para></listitem>
276 <listitem><para><methodname>isOptions()</methodname></para></listitem>
277 </itemizedlist>
279 <para>
280 これらの主な使用法は、RESTfult な
281 <acronym>MVC</acronym> アーキテクチャを作成することです。
282 </para>
283 </sect3>
285 <sect3 id="zend.controller.request.http.ajax">
286 <title>AJAX リクエストの検出</title>
288 <para>
289 <classname>Zend_Controller_Request_Http</classname> には、
290 <acronym>AJAX</acronym> リクエストを検出するための基本的なメソッド
291 <methodname>isXmlHttpRequest()</methodname> が用意されています。
292 このメソッドは、<acronym>HTTP</acronym> リクエストヘッダ
293 <emphasis>X-Requested-With</emphasis> に
294 'XMLHttpRequest' という値が設定されているかどうかを調べ、
295 設定されている場合に <constant>TRUE</constant> を返します。
296 </para>
298 <para>
299 現時点では、次の JS ライブラリがデフォルトでこのヘッダを渡すようです。
300 </para>
302 <itemizedlist>
303 <listitem><para>Prototype/Scriptaculous (その他
304 Prototype 系のライブラリ)</para></listitem>
305 <listitem><para>Yahoo! UI Library</para></listitem>
306 <listitem><para>jQuery</para></listitem>
307 <listitem><para>MochiKit</para></listitem>
308 </itemizedlist>
310 <para>
311 大半の <acronym>AJAX</acronym> ライブラリは、独自の <acronym>HTTP</acronym> リクエストヘッダを送信できます。
312 ご利用のライブラリがこのヘッダを送信していない場合は、
313 自分でこのヘッダを追加することで
314 <methodname>isXmlHttpRequest()</methodname> メソッドの動作を期待通りにできます。
315 </para>
316 </sect3>
317 </sect2>
319 <sect2 id="zend.controller.request.subclassing">
320 <title>リクエストオブジェクトのサブクラスの作成</title>
322 <para>
323 すべてのリクエストオブジェクトクラスは、抽象クラス
324 <classname>Zend_Controller_Request_Abstract</classname> を継承しています。
325 このクラスでは、次のようなメソッドを定義しています。
326 </para>
328 <programlisting language="php"><![CDATA[
329 abstract class Zend_Controller_Request_Abstract
330 {
331 /**
332 * @return string
333 */
334 public function getControllerName();
336 /**
337 * @param string $value
338 * @return self
339 */
340 public function setControllerName($value);
342 /**
343 * @return string
344 */
345 public function getActionName();
347 /**
348 * @param string $value
349 * @return self
350 */
351 public function setActionName($value);
353 /**
354 * @return string
355 */
356 public function getControllerKey();
358 /**
359 * @param string $key
360 * @return self
361 */
362 public function setControllerKey($key);
364 /**
365 * @return string
366 */
367 public function getActionKey();
369 /**
370 * @param string $key
371 * @return self
372 */
373 public function setActionKey($key);
375 /**
376 * @param string $key
377 * @return mixed
378 */
379 public function getParam($key);
381 /**
382 * @param string $key
383 * @param mixed $value
384 * @return self
385 */
386 public function setParam($key, $value);
388 /**
389 * @return array
390 */
391 public function getParams();
393 /**
394 * @param array $array
395 * @return self
396 */
397 public function setParams(array $array);
399 /**
400 * @param boolean $flag
401 * @return self
402 */
403 public function setDispatched($flag = true);
405 /**
406 * @return boolean
407 */
408 public function isDispatched();
409 }
410 ]]></programlisting>
412 <para>
413 リクエストオブジェクトは、リクエスト環境のコンテナとなります。
414 コントローラチェインが知っておくべきことは、
415 コントローラやアクション、オプションパラメータ、ディスパッチ状況
416 を取得したり設定したりする方法だけです。
417 デフォルトでは、リクエストオブジェクトが
418 コントローラおよびアクションを決定する際には
419 キー controller あるいは action を使用します。
420 </para>
422 <para>
423 このクラスかその派生クラスのいずれかを継承したクラスを作成することで、
424 上で説明した作業を独自のものに変更したクラスを作成できます。
425 例としては、たとえば <link linkend="zend.controller.request.http"><acronym>HTTP</acronym>
426 環境用</link> のクラスや <acronym>CLI</acronym> 環境用、<acronym>PHP</acronym>-GTK 環境用のクラスがあります。
427 </para>
428 </sect2>
429 </sect1>
430 <!--
431 vim:se ts=4 sw=4 et:
432 -->