documentation/manual/zh/module_specs/Zend_Http_Client.xml

   1 <sect1 id="zend.http.client">
   2     <title>Zend_Http_Client - 介绍</title>
   3
   4     <sect2 id="zend.http.client.introduction">
   5         <title>介绍</title>
   6         <para>
   7             Zend_Http_Client 提供了一个简单的界面来执行HTTP请求。Zend_Http_Client 支持
   8             作为一个 HTTP 客户端应有的大多数简单功能，也包括象HTTP认证和文件上传等更加
   9             复杂的功能。成功的请求和大多数失败的请求将返回一个 Zend_Http_Response 对象，
  10             该对象提供了对响应的头部信息和主体信息的访问。
  11             （见<xref linkend="zend.http.response" />）
  12         </para>
  13         <para>
  14             构造器类可选的第一个参数可以是一个URL（字符串或者 Zend_Uri_Http 对象），
  15             第二个可选参数是一个包含配置参数的数组。这两个参数也可以全空，之后由
  16             setUri()和setConfig()方法提供。
  17             <example id="zend.http.client.introduction.example-1">
  18                 <title>初始化一个 Zend_Http_Client 对象</title>
  19                 <programlisting role="php"><![CDATA[
  20 $client = new Zend_Http_Client('http://example.org', array(
  21     'maxredirects' => 0,
  22     'timeout'      => 30));
  23
  24 // 上述代码和下面的代码是两种不同的写法
  25 $client = new Zend_Http_Client();
  26 $client->setUri('http://example.org');
  27 $client->setConfig(array(
  28     'maxredirects' => 0,
  29     'timeout'      => 30));
  30 ]]>
  31                 </programlisting>
  32             </example>
  33         </para>
  34     </sect2>
  35     <sect2 id="zend.http.client.configuration">
  36         <title>配置参数</title>
  37         <para>
  38             构造器和 setConfig() 方法接受一个复合的配置参数数组，因为这些配置参数
  39             有一个缺省值，所以是否配置这些参数都是可选的。
  40             <table id="zend.http.client.configuration.table">
  41                 <title>Zend_Http_Client 配置参数</title>
  42                 <tgroup cols="4">
  43                     <thead>
  44                         <row>
  45                             <entry>参数</entry>
  46                             <entry>描述</entry>
  47                             <entry>值的类型</entry>
  48                             <entry>缺省值</entry>
  49                         </row>
  50                     </thead>
  51                     <tbody>
  52                         <row>
  53                             <entry>maxredirects</entry>
  54                             <entry>随后的重定向的最大值 (0 = none)</entry>
  55                             <entry>整数</entry>
  56                             <entry>5</entry>
  57                         </row>
  58                         <row>
  59                             <entry>strict</entry>
  60                             <entry>是否执行头部名称的确认，当设置为 False 时，将忽略确认，通常情况下不应改变这个参数的值。</entry>
  61                             <entry>布尔值</entry>
  62                             <entry>true</entry>
  63                         </row>
  64                         <row>
  65                             <entry>strictredirects</entry>
  66                             <entry>重定向时是否严格遵守 RFC (见 <xref linkend="zend.http.client.redirections" />)</entry>
  67                             <entry>布尔值</entry>
  68                             <entry>false</entry>
  69                         </row>
  70                         <row>
  71                             <entry>useragent</entry>
  72                             <entry>用户代理的识别字符串（含在请求的头部信息内）</entry>
  73                             <entry>字符串</entry>
  74                             <entry>'Zend_Http_Client'</entry>
  75                         </row>
  76                         <row>
  77                             <entry>timeout</entry>
  78                             <entry>连接超时 (单位是秒)</entry>
  79                             <entry>整数</entry>
  80                             <entry>10</entry>
  81                         </row>
  82                         <row>
  83                             <entry>httpversion</entry>
  84                             <entry>HTTP 协议版本 (通常是 '1.1' 或 '1.0')</entry>
  85                             <entry>字符串</entry>
  86                             <entry>'1.1'</entry>
  87                         </row>
  88                         <row>
  89                             <entry>adapter</entry>
  90                             <entry>连接适配器类时使用（见 <xref linkend="zend.http.client.adapters" />）</entry>
  91                             <entry>多种类型</entry>
  92                             <entry>'Zend_Http_Client_Adapter_Socket'</entry>
  93                         </row>
  94                         <row>
  95                             <entry>keepalive</entry>
  96                             <entry>是否允许与服务器之间的 keep-alive 连接。如果在同一台服务器上
  97                             执行几个互相关联的请求时，keep-alive 连接是有用的而且有可能提高性能。</entry>
  98                             <entry>布尔值</entry>
  99                             <entry>false</entry>
 100                         </row>
 101                         <row>
 102                             <entry>storeresponse</entry>
 103                             <entry>是否保存上次的响应结果，以备今后使用getLastResponse()重新获取。如果设置为 false，getLastResponse() 将返回空。</entry>
 104                             <entry>布尔值</entry>
 105                             <entry>true</entry>
 106                         </row>
 107                     </tbody>
 108                 </tgroup>
 109             </table>
 110         </para>
 111     </sect2>
 112     <sect2 id="zend.http.client.basic-requests">
 113         <title>执行基本 HTTP 请求</title>
 114         <para>
 115             使用 request() 方法执行简单 HTTP 请求是件非常容易的事情，3行代码即可搞定：
 116             <example id="zend.http.client.basic-requests.example-1">
 117                 <title>执行一个简单的 GET 请求</title>
 118                 <programlisting role="php"><![CDATA[
 119 $client = new Zend_Http_Client('http://example.org');
 120 $response = $client->request();
 121 ]]>
 122                 </programlisting>
 123             </example>
 124             request() 带一个可选的参数 - 请求方法，它可以是 GET, POST, PUT, HEAD,
 125             DELETE, TRACE, OPTIONS 或 CONNECT 等由 HTTP 协议定义的方法。
 126             <footnote>
 127               <para>
 128                 见 RFC 2616 - <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html" />.
 129               </para>
 130             </footnote>.
 131             为了方便起见，这些都被定义为类的常量：即
 132             Zend_Http_Request::GET, Zend_Http_Request::POST 等等。
 133         </para>
 134         <para>
 135             如果没有指定请求方法，则使用最后一次 setMethod() 设定的请求方法。
 136             如果从未使用 setMethod()，那么缺省的请求方法是 GET（见上述的例子）。
 137             <example id="zend.http.client.basic-requests.example-2">
 138                 <title>使用 GET 以外的请求方法</title>
 139                 <programlisting role="php"><![CDATA[
 140 // 执行一个 POST 请求
 141 $response = $client->request('POST');
 142
 143 // 另外一种执行 POST 请求的方式
 144 $client->setMethod(Zend_Http_Client::POST);
 145 $response = $client->request();
 146 ]]>
 147                 </programlisting>
 148             </example>
 149         </para>
 150     </sect2>
 151
 152     <sect2 id="zend.http.client.parameters">
 153         <title>添加 GET 和 POST 参数 </title>
 154         <para>
 155             在一个HTTP请求中添加GET参数是非常简单的，既可以通过把参数指定为
 156             URL的一部分，也可以通过使用 setParameterGet() 方法来添加。这个方
 157             法把把GET参数的名称作为它的第一个参数，把GET参数的值作为它的第二
 158             个参数。为了方便起见，setParameterGet() 方法也能接受单个复合数组
 159             （名称 => 值）的 GET 参数，这种方式对于需要设置几个 GET 参数时更
 160             加方便。
 161             <example id="zend.http.client.parameters.example-1">
 162                 <title>设置 GET 参数</title>
 163                 <programlisting role="php"><![CDATA[
 164 // 使用 setParameterGet 方法设置一个 GET 参数
 165 $client->setParameterGet('knight', 'lancelot');
 166
 167 // 设置 URL 的等效方法
 168 $client->setUri('http://example.com/index.php?knight=lancelot');
 169
 170 // 一次添加几个参数
 171 $client->setParameterGet(array(
 172     'first_name'  => 'Bender',
 173     'middle_name' => 'Bending'
 174     'made_in'     => 'Mexico',
 175 ));
 176 ]]>
 177                 </programlisting>
 178             </example>
 179         </para>
 180         <para>
 181             虽然 GET 参数可以和任何请求方法一起发送，但 POST 参数只能在 POST
 182             请求内发送。给一个请求添加 POST 参数与添加 GET 参数非常类似，是由
 183             setParameterPost() 方法完成的，该方法在结构上与 setParameterGet()
 184             方法很相似。
 185             <example id="zend.http.client.parameters.example-2">
 186                 <title>设置 POST 参数</title>
 187                 <programlisting role="php"><![CDATA[
 188 // 设置一个 POST 参数
 189 $client->setParameterPost('language', 'fr');
 190
 191 // 设置几个 POST 参数，其中的一个参数有几个值
 192 $client->setParameterPost(array(
 193     'language'  => 'es',
 194     'country'   => 'ar',
 195     'selection' => array(45, 32, 80)
 196 ));
 197 ]]>
 198                 </programlisting>
 199             </example>
 200             需要注意的是，当发送 POST 请求时，即可设置GET参数，也可设置POST参数。
 201             另一方面，如果针对一个非 POST 请求设置 POST 参数，将不会被触发或给出
 202             报错，因为它是没有用的。除非请求是一个 POST 请求，POST 参数都会被简
 203             单地忽略掉。
 204         </para>
 205     </sect2>
 206
 207     <sect2 id="zend.http.client.accessing_last">
 208         <title>访问最后一次的请求和响应</title>
 209         <para>
 210             Zend_Http_Client 提供了访问客户端最后一次发送的请求和访问客户端最后
 211             一次接收到的响应的方法。
 212             <code>Zend_Http_Client->getLastRequest()</code> 不需要设置参数，同时
 213             返回最后一次客户端发送的HTTP请求字符串。同样，
 214             <code>Zend_Http_Client->getLastResponse()</code> 返回客户端接收到的
 215             最后一次<link linkend="zend.http.response">Zend_Http_Response</link> 对象。
 216         </para>
 217     </sect2>
 218
 219 </sect1>
 220
 221 <!--
 222 vim:se ts=4 sw=4 et:
 223 -->