svn: /pear/peardoc/trunk/en/package/http/http-request2/ adapters.xml config.xml request.xml

avb                                      Sat, 07 Apr 2012 12:12:51 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=324939

Log:
Update docs for release 2.1.0
Address issue #19238
Remove misleading info about verify_peer vs proxies, this seems to work OK here

Bug: http://pear.php.net/bugs/19238 (unknown)
     
Changed paths:
    U   pear/peardoc/trunk/en/package/http/http-request2/adapters.xml
    U   pear/peardoc/trunk/en/package/http/http-request2/config.xml
    U   pear/peardoc/trunk/en/package/http/http-request2/request.xml

Modified: pear/peardoc/trunk/en/package/http/http-request2/adapters.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/adapters.xml 2012-04-07 10:14:34 UTC (rev 324938)
+++ pear/peardoc/trunk/en/package/http/http-request2/adapters.xml 2012-04-07 12:12:51 UTC (rev 324939)
@@ -66,26 +66,11 @@

  <refsection xml:id="package.http.http-request2.adapters.socket">
   <info><title>Socket Adapter Issues</title></info>
-  <itemizedlist>
-   <listitem><simpara>
-    Due to <link xmlns:xlink="http://www.w3.org/1999/xlink"
-     xlink:href="&url.php.bugs;47030">PHP bug #47030</link> <literal>ssl_verify_host</literal>
-    configuration parameter is completely useless. When <literal>ssl_verify_peer</literal> is
-    switched off <emphasis>no host validation will be performed</emphasis>, when
-    <literal>ssl_verify_peer</literal> is on host validation will always be performed as part of
-    peer validation.
-   </simpara></listitem>
-   <listitem><simpara>
-    When doing a <literal>https://</literal> request through proxy, SSL peer validation will always
-    fail (PHP considers that script is connected to a proxy server but the certificate presented is
-    obviously for the remote host). Therefore <literal>ssl_verify_peer</literal> should be off when
-    using proxy.
-   </simpara></listitem>
-  </itemizedlist>
   <para>
-   Note, that the above two problems mean that no peer validation whatsoever is possible when doing a
-   <literal>https://</literal> request through proxy using Socket adapter. If this is an issue for
-   you, consider using Curl Adapter instead.
+   Due to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.php.bugs;47030">PHP bug
+   #47030</link> <literal>ssl_verify_host</literal> configuration parameter is useless without
+   <literal>ssl_verify_peer</literal>. When the latter is switched off <emphasis>no host validation
+    will be performed</emphasis>.
   </para>
  </refsection>

@@ -128,6 +113,13 @@
    they were added.
   </para>
   <para>
+   Since release 2.1.0 it is possible to specify a request URL to
+   <function>addResponse</function>. <function>sendRequest</function> will only return responses
+   without an explicit URL set or having the same URL as the request. It is recommended that you set
+   explicit URLs either for all responses or for none of them, otherwise the behaviour will be
+   difficult to predict.
+  </para>
+  <para>
    <example>
     <title>Returning responses and throwing exceptions</title>
     <programlisting role="php"><![CDATA[
@@ -137,6 +129,13 @@
 $mock = new HTTP_Request2_Adapter_Mock();
 $mock->addResponse(
     "HTTP/1.1 200 OK\r\n" .
+    "Connection: close\r\n" .
+    "\r\n" .
+    "Explicit response for example.org",
+    'http://example.org/'
+);
+$mock->addResponse(
+    "HTTP/1.1 200 OK\r\n" .
     "Content-Length: 32\r\n" .
     "Connection: close\r\n" .
     "\r\n" .
@@ -161,12 +160,20 @@
 } catch (Exception $e) {
     echo "Error: " . $e->getMessage() . "\r\n";
 }
+
+// The response for example.org was ignored by previous requests
+$requestOrg = new HTTP_Request2(
+    'http://example.org/', HTTP_Request2::METHOD_GET,
+    array('adapter' => $mock)
+);
+echo "Response: " . $requestOrg->send()->getBody() . "\r\n";
 ]]>
     </programlisting>
     <simpara>The above code will output:</simpara>
     <screen><![CDATA[
 Response: Nothing to see here, move along.
 Error: The server is on fire!
+Response: Explicit response for example.org
 ]]>
     </screen>
    </example>

Modified: pear/peardoc/trunk/en/package/http/http-request2/config.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/config.xml 2012-04-07 10:14:34 UTC (rev 324938)
+++ pear/peardoc/trunk/en/package/http/http-request2/config.xml 2012-04-07 12:12:51 UTC (rev 324939)
@@ -141,6 +141,21 @@
      </thead>
      <tbody>
       <row valign="top">
+       <entry><literal>proxy</literal></entry>
+       <entry>Proxy configuration given as an URL, e.g.
+        <literal>'socks5://localhost:1080'</literal>, URL is parsed and separate parameters
+        described below are set (since <emphasis>2.1.0</emphasis>)</entry>
+       <entry>&type.string;</entry>
+       <entry>N/A</entry>
+      </row>
+      <row valign="top">
+       <entry><literal>proxy_type</literal></entry>
+       <entry>Proxy type, either <literal>'http'</literal> or <literal>'socks5'</literal> (since
+        <emphasis>2.1.0</emphasis>)</entry>
+       <entry>&type.string;</entry>
+       <entry><literal>'http'</literal></entry>
+      </row>
+      <row valign="top">
        <entry><literal>proxy_host</literal></entry>
        <entry>Proxy server host</entry>
        <entry>&type.string;</entry>
@@ -189,8 +204,7 @@
       <row valign="top">
        <entry><literal>ssl_verify_peer</literal></entry>
        <entry>Whether to verify peer's SSL certificate. Note that this is on by default, to follow
-        the behaviour of modern browsers and current cURL version. <link
-         linkend="package.http.http-request2.adapters.socket">Issues with Socket Adapter.</link></entry>
+        the behaviour of modern browsers and current cURL version.</entry>
        <entry>&type.bool;</entry>
        <entry>&true;</entry>
       </row>

Modified: pear/peardoc/trunk/en/package/http/http-request2/request.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/request.xml 2012-04-07 10:14:34 UTC (rev 324938)
+++ pear/peardoc/trunk/en/package/http/http-request2/request.xml 2012-04-07 12:12:51 UTC (rev 324939)
@@ -177,6 +177,20 @@
   </example>
   </para>
   <para>
+   <function>addUpload</function> can accept either a string with a local file name or a pointer to
+   an open file, as returned by <link xmlns:xlink="http://www.w3.org/1999/xlink"
+    xlink:href="&url.php.lookup;fopen"><function>fopen</function></link>. You currently can't
+   directly pass a string with the file contents, however you can pass a pointer to <link
+    xmlns:xlink="http://www.w3.org/1999/xlink"
+    xlink:href="http://php.net/manual/en/wrappers.php.php"><literal>php://memory</literal> or
+    <literal>php://temp</literal></link>:
+   <programlisting role="php"><![CDATA[
+$fp = fopen('php://temp/maxmemory:1048576', 'r+');
+fwrite($fp, generateFileUploadData());
+$request->addUpload('stuff', $fp, 'custom.name', 'application/octet-stream');
+    ]]></programlisting>
+  </para>
+  <para>
    HTTP request body can also be set directly, by providing a string or a filename to <phd:pearapi phd:package="HTTP_Request2"
    phd:linkend="HTTP_Request2::setBody" /> method. This is the only way to set a request body for
    non-<literal>POST</literal> request.


--
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php