| blob | 83acd29e314811998b07caa8c3dd03971f96bc43 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <!-- EN-Revision: 20779 -->
4 <sect1 id="zend.http.response">
5 <title>Zend_Http_Response</title>
7 <sect2 id="zend.http.response.introduction">
8 <title>導入</title>
9 <para>
10 <classname>Zend_Http_Response</classname> は、<acronym>HTTP</acronym> レスポンスに簡単にアクセスできるようにします。
11 また、<acronym>HTTP</acronym> レスポンスメッセージをパースするための静的メソッド群も提供します。
12 通常は、<classname>Zend_Http_Response</classname> は <classname>Zend_Http_Client</classname>
13 リクエストの返す結果として使用します。
14 </para>
15 <para>
16 ほとんどの場合は、Zend_Http_Response オブジェクトのインスタンスを作成するには
17 fromString() メソッドを使用します。これは、<acronym>HTTP</acronym>
18 レスポンスメッセージを含む文字列を受け取って新しい
19 Zend_Http_Response オブジェクトを返します。
20 <example id="zend.http.response.introduction.example-1">
21 <title>ファクトリメソッドを使用した Zend_Http_Response オブジェクトの作成</title>
22 <programlisting language="php"><![CDATA[
23 $str = '';
24 $sock = fsockopen('www.example.com', 80);
25 $req = "GET / HTTP/1.1\r\n" .
26 "Host: www.example.com\r\n" .
27 "Connection: close\r\n" .
28 "\r\n";
30 fwrite($sock, $req);
31 while ($buff = fread($sock, 1024))
32 $str .= $sock;
34 $response = Zend_Http_Response::fromString($str);
35 ]]></programlisting>
36 </example>
37 </para>
38 <para>
39 コンストラクタを使用して新しいオブジェクトを作成することもできます。
40 その際には、レスポンスの全パラメータを指定します。
41 </para>
42 <para>
43 <code>
44 public function __construct($code, $headers, $body = null, $version = '1.1', $message = null)
45 </code>
46 </para>
47 <itemizedlist>
48 <listitem>
49 <para>
50 <varname>$code</varname>: <acronym>HTTP</acronym> レスポンスコード (たとえば 200 や 404 など)。
51 </para>
52 </listitem>
53 <listitem>
54 <para>
55 <varname>$headers</varname>: <acronym>HTTP</acronym> レスポンスヘッダの連想配列 (たとえば 'Host' => 'example.com' など)。
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 <varname>$body</varname>: レスポンス本文の文字列。
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 <varname>$version</varname>: <acronym>HTTP</acronym> レスポンスのバージョン (通常は 1.0 あるいは 1.1)。
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 <varname>$message</varname>: <acronym>HTTP</acronym> レスポンスメッセージ (たとえば 'OK' や 'Internal Server Error' など)。
71 指定しなかった場合は、レスポンスコードに応じたメッセージが設定されます。
72 </para>
73 </listitem>
74 </itemizedlist>
75 </sect2>
76 <sect2 id="zend.http.response.testers">
77 <title>真偽チェック用のメソッド</title>
78 <para>
79 <classname>Zend_Http_Response</classname> のインスタンスを取得すると、
80 レスポンスの種類を調べるためのメソッドが使用できるようになります。
81 これらのメソッドは、すべて <constant>TRUE</constant> あるいは <constant>FALSE</constant> を返します。
82 <itemizedlist>
83 <listitem>
84 <para>
85 <code>Boolean isSuccessful()</code>: リクエストが成功したかどうかを調べます。
86 <acronym>HTTP</acronym> レスポンスコードが 1xx か 2xx であった場合に <constant>TRUE</constant> を返します。
87 </para>
88 </listitem>
89 <listitem>
90 <para>
91 <code>Boolean isError()</code>: レスポンスコードがエラーを意味しているかどうかを調べます。
92 <acronym>HTTP</acronym> レスポンスコードが 4xx (クライアントのエラー) あるいは
93 5xx (サーバのエラー) であった場合に <constant>TRUE</constant> を返します。
94 </para>
95 </listitem>
96 <listitem>
97 <para>
98 <code>Boolean isRedirect()</code>: レスポンスがリダイレクトされているかどうかを調べます。
99 <acronym>HTTP</acronym> レスポンスコードが 3xx であった場合に <constant>TRUE</constant> を返します。
100 </para>
101 </listitem>
102 </itemizedlist>
103 <example id="zend.http.response.testers.example-1">
104 <title>isError() メソッドの使用によるレスポンスの検証</title>
105 <programlisting language="php"><![CDATA[
106 if ($response->isError()) {
107 echo "データ転送エラー。\n"
108 echo "サーバからの応答: " . $response->getStatus() .
109 " " . $response->getMessage() . "\n";
110 }
111 // .. ここでレスポンスを処理します...
112 ]]></programlisting>
113 </example>
114 </para>
115 </sect2>
116 <sect2 id="zend.http.response.acessors">
117 <title>アクセス用メソッド群</title>
118 <para>
119 レスポンスオブジェクトの本来の目的は、レスポンスパラメータに簡単にアクセスすることです。
120 <itemizedlist>
121 <listitem>
122 <para>
123 <code>int getStatus()</code>: <acronym>HTTP</acronym> レスポンスステータスコード
124 (たとえば 200 や 504 など) を取得します。
125 </para>
126 </listitem>
127 <listitem>
128 <para>
129 <code>string getMessage()</code>: <acronym>HTTP</acronym> レスポンスステータスのメッセージ
130 (たとえば "Not Found" や "Authorization Required" など) を取得します。
131 </para>
132 </listitem>
133 <listitem>
134 <para>
135 <code>string getBody()</code>: <acronym>HTTP</acronym> レスポンス本文をデコードしたものを取得します。
136 </para>
137 </listitem>
138 <listitem>
139 <para>
140 <code>string getRawBody()</code>: そのままの状態の、おそらくエンコードされている
141 <acronym>HTTP</acronym> レスポンス本文を取得します。たとえば GZIP などでエンコードされていたとしても、
142 それはデコードされません。
143 </para>
144 </listitem>
145 <listitem>
146 <para>
147 <code>array getHeaders()</code>: <acronym>HTTP</acronym> レスポンスヘッダを、連想配列形式
148 (たとえば 'Content-type' => 'text/html' など) で取得します。
149 </para>
150 </listitem>
151 <listitem>
152 <para>
153 <code>string|array getHeader($header)</code>: $header で指定した、
154 特定の <acronym>HTTP</acronym> レスポンスヘッダを取得します。
155 </para>
156 </listitem>
157 <listitem>
158 <para>
159 <code>string getHeadersAsString($status_line = true, $br = "\n")</code>:
160 ヘッダ全体を文字列として取得します。$status_line が <constant>TRUE</constant> の場合 (デフォルト) は、
161 最初のステータス行 (たとえば "HTTP/1.1 200 OK" など) も返されます。
162 改行は $br パラメータで指定します (たとえば "<br />" などにもできます)。
163 </para>
164 </listitem>
165 <listitem>
166 <para>
167 <code>string asString($br = "\n")</code>: レスポンスメッセージ全体を文字列として取得します。
168 改行は $br パラメータで指定します (たとえば "<br />" などにもできます)。
169 マジックメソッド __toString()
170 を使ってオブジェクトを文字列にキャストできます。
171 これは asString() へのプロキシとなります。
172 </para>
173 </listitem>
174 </itemizedlist>
175 <example id="zend.http.response.acessors.example-1">
176 <title>Zend_Http_Response へのアクセス用メソッドの使用</title>
177 <programlisting language="php"><![CDATA[
178 if ($response->getStatus() == 200) {
179 echo "リクエストの結果は次のようになりました。<br />";
180 echo $response->getBody();
181 } else {
182 echo "データの取得時にエラーが発生しました。<br />";
183 echo $response->getStatus() . ": " . $response->getMessage();
184 }
185 ]]></programlisting>
186 </example>
187 <note>
188 <title>常に返り値をチェックする</title>
189 <para>
190 レスポンスには同じヘッダを複数含めることができるので、
191 getHeader() メソッドや getHeaders() メソッドの返す結果は
192 文字列の場合もあれば文字列の配列となる場合もあります。
193 返された値が文字列なのか配列なのかを常にチェックするようにしましょう。
194 </para>
195 </note>
196 <example id="zend.http.response.acessors.example-2">
197 <title>レスポンスヘッダへのアクセス</title>
198 <programlisting language="php"><![CDATA[
199 $ctype = $response->getHeader('Content-type');
200 if (is_array($ctype)) $ctype = $ctype[0];
202 $body = $response->getBody();
203 if ($ctype == 'text/html' || $ctype == 'text/xml') {
204 $body = htmlentities($body);
205 }
207 echo $body;
208 ]]></programlisting>
209 </example>
210 </para>
211 </sect2>
213 <sect2 id="zend.http.response.static_parsers">
214 <title>静的 HTTP レスポンスパーサ</title>
215 <para>
216 <classname>Zend_Http_Response</classname> クラスには、内部で使用するメソッドもいくつか含まれています。
217 これは、<acronym>HTTP</acronym> レスポンスメッセージを処理したりパースしたりするためのものです。
218 これらのメソッドは静的メソッドとして公開されています。
219 つまり外部からでも使用できるということです。特にインスタンスを作成しなくても、
220 レスポンスの一部を抽出したりなどといった目的で使用可能です。
221 <itemizedlist>
222 <listitem>
223 <para>
224 <code>int Zend_Http_Response::extractCode($response_str)</code>:
225 <acronym>HTTP</acronym> レスポンスコード (たとえば 200 や 404 など)
226 を $response_str から抽出し、それを返します。
227 </para>
228 </listitem>
229 <listitem>
230 <para>
231 <code>string Zend_Http_Response::extractMessage($response_str)</code>:
232 <acronym>HTTP</acronym> レスポンスメッセージ (たとえば "OK" や "File Not Found" など)
233 を $response_str から抽出し、それを返します。
234 </para>
235 </listitem>
236 <listitem>
237 <para>
238 <code>string Zend_Http_Response::extractVersion($response_str)</code>:
239 <acronym>HTTP</acronym> バージョン (たとえば 1.1 や 1.0 など)
240 を $response_str から抽出し、それを返します。
241 </para>
242 </listitem>
243 <listitem>
244 <para>
245 <code>array Zend_Http_Response::extractHeaders($response_str)</code>:
246 <acronym>HTTP</acronym> レスポンスヘッダを $response_str から抽出し、それを配列で返します。
247 </para>
248 </listitem>
249 <listitem>
250 <para>
251 <code>string Zend_Http_Response::extractBody($response_str)</code>:
252 <acronym>HTTP</acronym> レスポンス本文を $response_str から抽出し、それを返します。
253 </para>
254 </listitem>
255 <listitem>
256 <para>
257 <code>string Zend_Http_Response::responseCodeAsText($code = null, $http11 = true)</code>:
258 レスポンスコード $code に対応する、標準的な <acronym>HTTP</acronym> レスポンスメッセージを取得します。
259 たとえば $code が 500 の場合は "Internal Server Error" を返します。
260 $http11 が <constant>TRUE</constant> の場合 (デフォルト) は <acronym>HTTP</acronym>/1.1 のメッセージを、
261 そうでない場合は <acronym>HTTP</acronym>/1.0 のメッセージを返します。
262 $code を省略した場合は、このメソッドは、すべての既知の <acronym>HTTP</acronym>
263 レスポンスコードを連想配列 (code => message) で返します。
264 </para>
265 </listitem>
266 </itemizedlist>
267 </para>
268 <para>
269 パーサメソッド以外にも、このクラスには
270 一般的な <acronym>HTTP</acronym> レスポンスエンコーディングに対応したデコーダが含まれています。
271 <itemizedlist>
272 <listitem>
273 <para>
274 <code>string Zend_Http_Response::decodeChunkedBody($body)</code>:
275 "Content-Transfer-Encoding: Chunked" の本文をデコードします。
276 </para>
277 </listitem>
278 <listitem>
279 <para>
280 <code>string Zend_Http_Response::decodeGzip($body)</code>:
281 "Content-Encoding: gzip" の本文をデコードします。
282 </para>
283 </listitem>
284 <listitem>
285 <para>
286 <code>string Zend_Http_Response::decodeDeflate($body)</code>:
287 "Content-Encoding: deflate" の本文をデコードします。
288 </para>
289 </listitem>
290 </itemizedlist>
291 </para>
292 </sect2>
293 </sect1>
294 <!--
295 vim:se ts=4 sw=4 et:
296 -->