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

Modified: pear/peardoc/trunk/en/package/http/http-request2/adapters.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/adapters.xml	2009-09-22 21:57:43 UTC (rev 288592)
+++ pear/peardoc/trunk/en/package/http/http-request2/adapters.xml	2009-09-22 22:04:29 UTC (rev 288593)
@@ -93,13 +93,14 @@
   <info><title>Curl Adapter Issues</title></info>
   <para>
    When doing a <literal>POST</literal> request with file uploads or reading the request body from
-   file, <classname>HTTP_Request2</classname> streams files from disc to reduce memory consumption
-   and to allow the request monitoring. This is done by setting up a
+   file, <classname>HTTP_Request2</classname> streams files from disk to reduce memory consumption
+   and to allow monitoring the request progress. This is done by setting up a
    <constant>CURLOPT_READFUNCTION</constant> callback. PHP does not allow setting another callback,
    <constant>CURLOPT_IOCTLFUNCTION</constant> (see <link xmlns:xlink="http://www.w3.org/1999/xlink"
     xlink:href="&url.php.bugs;47204">PHP bug #47204</link>) so the request body can not be
-   &quot;rewinded&quot; when another request should be performed. Thus a <literal>POST</literal>
-   request to a resource protected by Digest authentication will always fail.
+   &quot;rewound&quot; when another request should be performed. Thus a <literal>POST</literal>
+   request to a resource protected by Digest authentication will always fail, since Digest scheme
+   requires two requests to be performed.
   </para>
  </refsection>


Modified: pear/peardoc/trunk/en/package/http/http-request2/intro.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/intro.xml	2009-09-22 21:57:43 UTC (rev 288592)
+++ pear/peardoc/trunk/en/package/http/http-request2/intro.xml	2009-09-22 22:04:29 UTC (rev 288593)
@@ -1,5 +1,10 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<refentry xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="package.http.http-request2.intro">
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.http.http-request2.intro"
+>
  <refnamediv>
   <refname>Introduction</refname>
   <refpurpose>Introduction to <classname>HTTP_Request2</classname></refpurpose>
@@ -29,6 +34,28 @@
  </refsection>
  <refsection xml:id="package.http.http-request2.intro.basic-example">
   <info><title>Basic Usage Example</title></info>
+   <para>
+    Performing a request with <classname>HTTP_Request2</classname> consists of the following steps
+    <itemizedlist>
+     <listitem><simpara>
+      Creating, <link linkend="package.http.http-request2.config">configuring</link> and <link
+      linkend="package.http.http-request2.request">populating</link> an instance of
+      <classname>HTTP_Request2</classname> class. At the very least you should set request URL and
+      maybe proxy parameters (if you are using proxy).
+     </simpara></listitem>
+     <listitem><simpara>
+      Calling <phd:pearapi phd:package="HTTP_Request2"
+       phd:linkend="HTTP_Request2::send">send</phd:pearapi> method of that instance. This will pass
+      control to <link linkend="package.http.http-request2.adapters">an Adapter</link> that will send
+      the request and read remote server's response. Request's progress may be monitored by using
+      <link linkend="package.http.http-request2.observers">Observers</link>
+     </simpara></listitem>
+     <listitem><simpara>
+      Processing the returned instance of <link
+       linkend="package.http.http-request2.response"><classname>HTTP_Request2_Response</classname></link>.
+     </simpara></listitem>
+    </itemizedlist>
+   </para>
   <example>
    <info>
     <title>

Modified: pear/peardoc/trunk/en/package/http/http-request2/request.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/request.xml	2009-09-22 21:57:43 UTC (rev 288592)
+++ pear/peardoc/trunk/en/package/http/http-request2/request.xml	2009-09-22 22:04:29 UTC (rev 288593)
@@ -26,8 +26,6 @@
    <example>
     <title>Setting <literal>GET</literal> parameters</title>
     <programlisting role="php"><![CDATA[
-require_once 'HTTP/Request2.php';
-
 $request = new HTTP_Request2('http://pear.php.net/bugs/search.php');
 $url = $request->getUrl();
 // Explicitly set use_brackets
@@ -49,18 +47,112 @@
  <refsection xml:id="package.http.http-request2.request.auth">
   <info><title>HTTP Authentication</title></info>
   <para>
+   <classname>HTTP_Request2</classname> supports both Basic and Digest authentication schemes
+   defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.rfc;2617">RFC
+   2617</link>. Authentication credentials can be set via <phd:pearapi
+   phd:package="HTTP_Request2" phd:linkend="HTTP_Request2::setAuth" /> method or given in the
+   request URL (but in the latter case authentication scheme will default to Basic).
+   <example>
+    <title>Setting authentication credentials</title>
+    <programlisting role="php"><![CDATA[
+// This will set credentials for basic auth
+$request = new HTTP_Request2('http://user:[email protected]/secret/');
+
+// This will set credentials for Digest auth
+$request->setAuth('user', 'password', HTTP_Request2::AUTH_DIGEST);
+    ]]></programlisting>
+   </example>
   </para>
+  <para>
+   There is currently <link linkend="package.http.http-request2.adapters.curl">an issue with Digest
+   authentication support in Curl Adapter</link> due to an underlying PHP cURL extension problem.
+  </para>
  </refsection>

  <refsection xml:id="package.http.http-request2.request.headers">
   <info><title>Request Headers and Cookies</title></info>
   <para>
+   Additional request headers can be set via <phd:pearapi
+   phd:package="HTTP_Request2" phd:linkend="HTTP_Request2::setHeader" /> method. It also allows
+   removing previosly set headers
+   <example>
+    <title>Setting request headers</title>
+    <programlisting role="php"><![CDATA[
+// setting one header
+$request->setHeader('Accept-Charset', 'utf-25');
+
+// setting several headers in one go
+$request->setHeader(array(
+    'Connection' => 'close',
+    'Referer'    => 'http://localhost/'
+));
+
+// removing a header
+$request->setHeader('User-Agent', null);
+    ]]></programlisting>
+   </example>
   </para>
+  <para>
+   Cookies can be added to the request via <function>setHeader</function> method, but a specialized <phd:pearapi
+   phd:package="HTTP_Request2" phd:linkend="HTTP_Request2::addCookie" /> method is also provided
+   <example>
+    <title>Adding cookies to the request</title>
+    <programlisting role="php"><![CDATA[
+$request->addCookie('CUSTOMER', 'WILE_E_COYOTE');
+$request->addCookie('PART_NUMBER', 'ROCKET_LAUNCHER_0001');
+    ]]></programlisting>
+   </example>
+  </para>
  </refsection>

  <refsection xml:id="package.http.http-request2.request.body">
   <info><title>Request Body</title></info>
   <para>
+   If you are doing a <literal>POST</literal> request with Content-Type
+   <literal>'application/x-www-form-urlencoded'</literal> or
+   <literal>'multipart/form-data'</literal> (in other words, emulating <literal>POST</literal> form
+   submission), you can add parameters via <phd:pearapi phd:package="HTTP_Request2"
+   phd:linkend="HTTP_Request2::addPostParameter" /> and file uploads via <phd:pearapi
+   phd:package="HTTP_Request2" phd:linkend="HTTP_Request2::addUpload" />.
+   <literal>HTTP_Request2</literal> will take care of generating proper request body. File
+   uploads will be streamed from disk by <phd:pearapi phd:package="HTTP_Request2"
+   phd:linkend="HTTP_Request2_MultipartBody" /> to reduce memory consumption.
+  <example>
+   <title>Emulating <literal>POST</literal> form submission</title>
+   <programlisting role="php"><![CDATA[
+$request = new HTTP_Request2('http://www.example.com/profile.php');
+$request->setMethod(HTTP_Request2::METHOD_POST)
+    ->addPostParameter('username', 'vassily')
+    ->addPostParameter(array(
+        'email' => '[email protected]',
+        'phone' => '+7 (495) 123-45-67'
+    ))
+    ->addUpload('avatar', './exploit.exe', 'me_and_my_cat.jpg', 'image/jpeg');
+   ]]></programlisting>
+  </example>
   </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.
+   <example>
+    <title>Setting &quot;raw&quot; request body</title>
+    <programlisting role="php"><![CDATA[
+$request = new HTTP_Request2('http://rpc.example.com');
+$request->setMethod(HTTP_Request2::METHOD_POST)
+    ->setHeader('Content-type: text/xml; charset=utf-8')
+    ->setBody(
+        "<?xml version=\"1.0\" encoding=\"utf-8\"?" . ">\r\n" .
+        "<methodCall>\r\n" .
+        " <methodName>foo.bar</methodName>\r\n" .
+        " <params>\r\n" .
+        "  <param><value><string>Hello, world!</string></value></param>\r\n" .
+        "  <param><value><int>42</int></value></param>\r\n" .
+        " </params>\r\n" .
+        "</methodCall>"
+    );
+    ]]></programlisting>
+   </example>
+  </para>
  </refsection>
 </refentry>