svn: /pear/peardoc/trunk/ en/package/http/http-request2/exceptions.xml en/package/http/http-request2/intro.xml en/package/http/http-request2/observers.xml en/package/http/http-request2/request.xml en/package/http/http-request2.xml entities/global.ent

Added: pear/peardoc/trunk/en/package/http/http-request2/exceptions.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/exceptions.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/package/http/http-request2/exceptions.xml	2011-03-02 16:22:37 UTC (rev 308860)
@@ -0,0 +1,157 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:phd="http://www.php.net/ns/phd"
+ version="lillet"
+ xml:id="package.http.http-request2.exceptions"
+>
+ <refnamediv>
+  <refname>Exceptions</refname>
+  <refpurpose>Handling package errors</refpurpose>
+ </refnamediv>
+ <refsection xml:id="package.http.http-request2.exceptions.overview">
+  <info>
+   <title>Exceptions overview</title>
+  </info>
+  <para>
+   All exceptions thrown in HTTP_Request2 are instances of <phd:pearapi
+    phd:package="HTTP_Request2" phd:linkend="HTTP_Request2_Exception" />.
+   Since release 2.0.0beta1, HTTP_Request2 tries to throw a specialized subclass of that class and
+   provide an error code when possible.
+  </para>
+  <para>
+   Checking for exception subclass and error code can help your application identify transient
+   failures (e.g. <classname>HTTP_Request2_MessageException</classname> with error code
+   <constant>HTTP_Request2_Exception::TIMEOUT</constant>). You can also use this information to
+   display a user friendly error message instead of displaying Exception message that is more
+   programmer friendly.
+  </para>
+  <para>
+   The following <classname>HTTP_Request2_Exception</classname> subclasses are available:
+   <variablelist>
+    <varlistentry>
+     <term><classname>HTTP_Request2_NotImplementedException</classname></term>
+     <listitem><simpara>Exception thrown in case of missing package features.</simpara></listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><classname>HTTP_Request2_LogicException</classname></term>
+     <listitem>
+      <simpara>Exception that represents error in the program logic. These are usually thrown before
+       request even starts.</simpara>
+      <simpara>This exception implies an error on part of the programmer, like passing an invalid
+       argument to a method or trying to use Curl Adapter when curl extension is disabled. They
+       are unlikely to happen in production except for those dealing with local files.</simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><classname>HTTP_Request2_ConnectionException</classname></term>
+     <listitem>
+      <simpara>Exception thrown when connection to a web or proxy server fails.</simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><classname>HTTP_Request2_MessageException</classname></term>
+     <listitem><simpara>Thrown when sending or receiving HTTP message fails (this implies that
+      connection succeeded, at least). Can be caused by network problems (e.g. timeout) or remote
+      server sending invalid data.</simpara></listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+
+ </refsection>
+ <refsection xml:id="package.http.http-request2.exceptions.codes">
+  <info>
+   <title>Error codes</title>
+  </info>
+  <para>
+   Subclasses of <classname>HTTP_Request2_Exception</classname> can contain two error codes:
+   <itemizedlist>
+    <listitem><simpara>Package error code, one of the constants described below. Can be accessed via
+     <function>getCode</function> method.</simpara></listitem>
+    <listitem><simpara>Native error code, as returned by an underlying PHP extension used by
+     <link linkend="package.http.http-request2.adapters">the Adapter</link>. Specifically, these are
+     the error codes returned by <link xmlns:xlink="http://www.w3.org/1999/xlink"
+      xlink:href="&url.php.lookup;stream_socket_client"><function>stream_socket_client</function></link>
+     for Socket Adapter and <link xmlns:xlink="http://www.w3.org/1999/xlink"
+      xlink:href="&url.php.lookup;curl_errno"><function>curl_errno</function></link> for Curl
+     Adapter. Native error code can be accessed via <phd:pearapi phd:package="HTTP_Request2"
+      phd:linkend="HTTP_Request2_Exception::getNativeCode" />.</simpara></listitem>
+   </itemizedlist>
+  </para>
+
+  <para>
+   The following package error codes are currently used:
+   <table>
+    <title>Error codes used by <classname>HTTP_Request2_LogicException</classname></title>
+    <tgroup cols="2">
+     <thead>
+      <row valign="top">
+       <entry>Constant</entry>
+       <entry>Meaning</entry>
+      </row>
+     </thead>
+
+     <tbody>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::INVALID_ARGUMENT</constant></entry>
+       <entry>An invalid argument was passed to a method.</entry>
+      </row>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::MISSING_VALUE</constant></entry>
+       <entry>Some required value was not available.</entry>
+      </row>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::MISCONFIGURATION</constant></entry>
+       <entry>Request cannot be processed due to errors in PHP configuration (e.g. trying to use
+        disabled PHP extension).</entry>
+      </row>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::READ_ERROR</constant></entry>
+       <entry>Error reading the local file.</entry>
+      </row>
+     </tbody>
+    </tgroup>
+
+   </table>
+
+   <table>
+    <title>Error codes used by <classname>HTTP_Request2_MessageException</classname></title>
+    <tgroup cols="2">
+     <thead>
+      <row valign="top">
+       <entry>Constant</entry>
+       <entry>Meaning</entry>
+      </row>
+     </thead>
+
+     <tbody>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::MALFORMED_RESPONSE</constant></entry>
+       <entry>Server returned a response that does not conform to HTTP protocol. This means that
+        even status line of response message could not be parsed.</entry>
+      </row>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::DECODE_ERROR</constant></entry>
+       <entry>Failure decoding Content-Encoding or Transfer-Encoding of response.</entry>
+      </row>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::TIMEOUT</constant></entry>
+       <entry>Operation timed out.</entry>
+      </row>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::TOO_MANY_REDIRECTS</constant></entry>
+       <entry>Number of redirects exceeded <literal>'max_redirects'</literal> <link
+        linkend="package.http.http-request2.config.table">configuration parameter</link>.</entry>
+      </row>
+      <row valign="top">
+       <entry><constant>HTTP_Request2_Exception::NON_HTTP_REDIRECT</constant></entry>
+       <entry>Redirect to a protocol other than <literal>http(s)://</literal>.</entry>
+      </row>
+     </tbody>
+    </tgroup>
+
+   </table>
+  </para>
+ </refsection>
+</refentry>
+

Modified: pear/peardoc/trunk/en/package/http/http-request2/intro.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/intro.xml	2011-03-02 13:09:56 UTC (rev 308859)
+++ pear/peardoc/trunk/en/package/http/http-request2/intro.xml	2011-03-02 16:22:37 UTC (rev 308860)
@@ -47,14 +47,16 @@
       Calling <function><phd:pearapi phd:package="HTTP_Request2"
        phd:linkend="HTTP_Request2::send">send</phd:pearapi></function> 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>
+      the request and read remote server's response. Request's progress may be monitored by
+      <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>.
-      An instance of <classname>HTTP_Request2_Exception</classname> can also be thrown by
-      <function>send</function> if response could not be received (completely or at all) or parsed.
+      An instance of <link
+       linkend="package.http.http-request2.exceptions"><classname>HTTP_Request2_Exception</classname></link>
+      can also be thrown by <function>send</function> if response could not be received (completely
+      or at all) or parsed.
      </simpara></listitem>
     </itemizedlist>
    </para>

Modified: pear/peardoc/trunk/en/package/http/http-request2/observers.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/observers.xml	2011-03-02 13:09:56 UTC (rev 308859)
+++ pear/peardoc/trunk/en/package/http/http-request2/observers.xml	2011-03-02 16:22:37 UTC (rev 308860)
@@ -64,6 +64,11 @@
      </simpara></listitem>
     </varlistentry>
     <varlistentry>
+     <term><literal>'sentBody'</literal> (since release 2.0.0beta1)</term>
+     <listitem><simpara>On sending the complete request body, <literal>'data'</literal> is the
+      length of request body (&type.integer;).</simpara></listitem>
+    </varlistentry>
+    <varlistentry>
      <term><literal>'receivedHeaders'</literal></term>
      <listitem><simpara>
       On receiving the response headers, <literal>'data'</literal> is
@@ -94,7 +99,7 @@
    </variablelist>
   </para>
   <note><para>
-   As the events are actually send by request Adapters, you can receive fewer or different events
+   As the events are actually sent by request Adapters, you can receive fewer or different events
    if you switch to another Adapter. Curl Adapter does not notify of <literal>'connect'</literal>,
    <literal>'disconnect'</literal> and <literal>'receivedEncodedBodyPart'</literal> events (it
    always uses <literal>'receivedBodyPart'</literal> as cURL extension takes care of decoding).

Modified: pear/peardoc/trunk/en/package/http/http-request2/request.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2/request.xml	2011-03-02 13:09:56 UTC (rev 308859)
+++ pear/peardoc/trunk/en/package/http/http-request2/request.xml	2011-03-02 16:22:37 UTC (rev 308860)
@@ -70,7 +70,7 @@
  </refsection>

  <refsection xml:id="package.http.http-request2.request.headers">
-  <info><title>Request Headers and Cookies</title></info>
+  <info><title>Request Headers</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
@@ -92,9 +92,15 @@
     ]]></programlisting>
    </example>
   </para>
+ </refsection>
+
+ <refsection xml:id="package.http.http-request2.request.cookies">
+  <info>
+   <title>Cookies</title>
+  </info>
   <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
+    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[
@@ -103,6 +109,45 @@
     ]]></programlisting>
    </example>
   </para>
+  <refsection xml:id="package.http.http-request2.request.cookiejar">
+   <info>
+    <title>Using cookie jar to manage cookies across requests</title>
+   </info>
+   <para>
+    Since release 2.0.0beta1 the package contains <phd:pearapi phd:package="HTTP_Request2"
+     phd:linkend="HTTP_Request2_CookieJar" /> class that can be used manage cookies across requests.
+    You can enable this functionality by passing either an existing instance of
+    <classname>HTTP_Request2_CookieJar</classname> or &true; to create a new instance to
+    <phd:pearapi phd:package="HTTP_Request2" phd:linkend="HTTP_Request2::setCookieJar" /> method.
+    Cookie Jar can be later accessed by <phd:pearapi phd:package="HTTP_Request2"
+     phd:linkend="HTTP_Request2::getCookieJar" />.
+   </para>
+   <para>
+    Cookie jar will automatically store cookies set in HTTP response and pass them to requests
+    with URLs matching cookie parameters. You can also manually add cookies to jar by using
+    <phd:pearapi phd:package="HTTP_Request2" phd:linkend="HTTP_Request2_CookieJar::store" /> method.
+   </para>
+   <para>
+    By default <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.publicsuffix;">Public
+    Suffix List</link> is used to check whether a cookie domain matches the given URL. The same list
+    is used to restrict cookie setting by Firefox, Chrome and Opera browsers. It can be disabled if
+    needed by <phd:pearapi phd:package="HTTP_Request2"
+     phd:linkend="HTTP_Request2_CookieJar::usePublicSuffixList" />.
+   </para>
+   <para>
+    <classname>HTTP_Request2_CookieJar</classname> implements
+    <interfacename>Serializable</interfacename> interface and thus can be easily serialized and
+    stored somewhere. You can control whether session cookies stored in a jar should be serialized
+    by calling <phd:pearapi phd:package="HTTP_Request2"
+     phd:linkend="HTTP_Request2_CookieJar::serializeSessionCookies" />.
+   </para>
+   <note><para>
+    When <classname>HTTP_Request2</classname> instance has a cookie jar set, <phd:pearapi
+     phd:package="HTTP_Request2" phd:linkend="HTTP_Request2::addCookie" /> method will add a cookie
+    to jar, rather than directly to <literal>'Cookie'</literal> header, using current request URL
+    for setting its <literal>'domain'</literal> and <literal>'path'</literal> components.
+   </para></note>
+  </refsection>
  </refsection>

  <refsection xml:id="package.http.http-request2.request.body">

Modified: pear/peardoc/trunk/en/package/http/http-request2.xml
===================================================================
--- pear/peardoc/trunk/en/package/http/http-request2.xml	2011-03-02 13:09:56 UTC (rev 308859)
+++ pear/peardoc/trunk/en/package/http/http-request2.xml	2011-03-02 16:22:37 UTC (rev 308860)
@@ -5,7 +5,9 @@
   <abstract>
    <para>
     PHP5 rewrite of <link linkend="package.http.http-request"><classname>HTTP_Request</classname></link>
-    package. Provides cleaner API and pluggable Adapters:
+    package (with some features from <link
+     linkend="package.http.http-client"><classname>HTTP_Client</classname></link>). Provides cleaner
+    API and pluggable Adapters:
     <itemizedlist>
      <listitem><simpara>
       Socket adapter, based on old <classname>HTTP_Request</classname> code,
@@ -19,9 +21,9 @@
     </itemizedlist>
    </para>
    <simpara>
-    Supports POST requests with data and file uploads, basic and digest
-    authentication, redirects, cookies, proxies, gzip and deflate encodings,
-    monitoring the request progress with Observers...
+    Supports POST requests with data and file uploads, basic and digest
+    authentication, cookies, managing cookies across requests, proxies, gzip and
+    deflate encodings, redirects, monitoring the request progress with Observers...
    </simpara>
   </abstract>
  </info>
@@ -32,5 +34,6 @@
   &package.http.http-request2.adapters;
   &package.http.http-request2.response;
   &package.http.http-request2.observers;
+  &package.http.http-request2.exceptions;
  </chapter>
 </book>

Modified: pear/peardoc/trunk/entities/global.ent
===================================================================
--- pear/peardoc/trunk/entities/global.ent	2011-03-02 13:09:56 UTC (rev 308859)
+++ pear/peardoc/trunk/entities/global.ent	2011-03-02 16:22:37 UTC (rev 308860)
@@ -143,6 +143,7 @@
 <!ENTITY url.phpform 'http://sourceforge.net/projects/phpform-ext/'>
 <!ENTITY url.phpunit 'http://www.phpunit.de/'>
 <!ENTITY url.phpunit.get 'http://pear.phpunit.de/get/'>
+<!ENTITY url.publicsuffix 'http://publicsuffix.org/'>
 <!ENTITY url.python.doc.modindex.optparse 'http://docs.python.org/library/module-optparse.html'>
 <!ENTITY url.recaptcha.recaptcha 'http://recaptcha.net/apidocs/captcha/'>
 <!ENTITY url.recaptcha.recaptcha.getapikey 'http://recaptcha.net/api/getkey'>