Document user-agent's undocumented feature: Custom request headers

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@209748 c90b9560-bf6c-de11-be94-00142212c4b1

appendices/wrappers.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.58 $ -->
+<!-- $Revision: 1.59 $ -->
 <appendix id="wrappers">
  <title>List of Supported Protocols/Wrappers</title>
  <para>
@@ -365,6 +365,40 @@ foreach($meta_data['wrapper_data'] as $response) {
     for the <literal>ssl://</literal> transport.
    </simpara>
   </note>
+
+  <para>
+   Custom headers may be sent with an HTTP request prior to
+   version 5 by taking advantage of a side-effect in the
+   handling of the <literal>user_agent</literal> INI setting.
+   Set <literal>user_agent</literal> to any valid string
+   (such as the default <literal>PHP/version</literal> setting)
+   followed by a carriage-return/line-feed pair and any
+   additional headers.
+   This method works in PHP4 and all later versions.
+  </para>
+  <para>
+   <example>
+    <title>Sending custom headers with an HTTP request</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+ini_set('user_agent', "PHP\r\nX-MyCustomHeader: Foo");
+
+$fp = fopen('http://www.example.com/index.php', 'r');
+?>
+]]>
+    </programlisting>
+    <para>Results in the following request being sent:</para>
+    <screen>
+<![CDATA[
+GET /index.php HTTP/1.0
+Host: www.example.com
+User-Agent: PHP
+X-MyCustomHeader: Foo
+]]>
+    </screen>
+   </example>
+  </para>
  </section>
 
  <section id="wrappers.ftp">