archived-doc-en/language/wrappers/http.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 296080 $ -->

<refentry xml:id="wrappers.http" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
 <refnamediv>
  <refname>HTTP and HTTPS</refname>
  <refpurpose>Accessing HTTP(s) URLs</refpurpose>
 </refnamediv>

 <refsect1 role="description"><!-- {{{ -->
  &reftitle.description;
  <para>
   Allows read-only access to files/resources via HTTP 1.0,
   using the HTTP GET method. A <literal>Host:</literal> header is sent with the request
   to handle name-based virtual hosts.  If you have configured
   a <link linkend="ini.user-agent">user_agent</link> string using
   your &php.ini; file or the stream context, it will also be included
   in the request.
  </para>
  <simpara>
   The stream allows access to the <emphasis>body</emphasis> of
   the resource; the headers are stored in the
   <varname>$http_response_header</varname> variable.
   Since PHP 4.3.0, the headers are available using
   <function>stream_get_meta_data</function>.
  </simpara>
  &warn.ssl-non-standard;
  <simpara>
   Redirects have been supported since PHP 4.0.5; if you are using
   an earlier version you will need to include trailing slashes in
   your URLs.  If it's important to know the URL of the resource where
   your document came from (after all redirects have been processed),
   you'll need to process the series of response headers returned by the
   stream.
  </simpara>
  <simpara>
   If you have set the <link linkend="ini.from">from</link> directive
   in &php.ini;, and do not define a <literal>From:</literal> header
   in the <xref linkend="context" />, then this value will be sent as the
   <literal>From:</literal> header in the HTTP request.
  </simpara>
 </refsect1><!-- }}} -->

 <refsect1 role="usage"> <!-- {{{ -->
  &reftitle.options;
  <itemizedlist>
   <listitem><simpara><filename>http://example.com</filename></simpara></listitem>
   <listitem><simpara><filename>http://example.com/file.php?var1=val1&amp;var2=val2</filename></simpara></listitem>
   <listitem><simpara><filename>http://user:password@example.com</filename></simpara></listitem>
   <listitem><simpara><filename>https://example.com</filename></simpara></listitem>
   <listitem><simpara><filename>https://example.com/file.php?var1=val1&amp;var2=val2</filename></simpara></listitem>
   <listitem><simpara><filename>https://user:password@example.com</filename></simpara></listitem>
  </itemizedlist>
 </refsect1> <!-- }}} -->

 <refsect1 role="options"><!-- {{{ -->
  &reftitle.options;
  <para>
   <table>
    <title>Wrapper Summary</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Attribute</entry>
       <entry>Supported</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>N/A</entry>
      </row>
      <row>
       <entry>Supports <function>stat</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>unlink</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>rename</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>mkdir</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>rmdir</function></entry>
       <entry>No</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1> <!-- }}} -->

 <refsect1 role="changelog"><!-- {{{ -->
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.3.0</entry>
       <entry>
        Added <literal>https://</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1><!-- }}} -->

 <refsect1 role="examples"><!-- {{{ -->
  &reftitle.examples;
  <example xml:id="wrappers.http.example.basic"><!-- {{{ -->
   <programlisting role="php">
<![CDATA[
<?php
$url = 'http://www.example.com/redirecting_page.php';

$fp = fopen($url, 'r');

/* Prior to PHP 4.3.0 use $http_response_header
   instead of stream_get_meta_data() */
$meta_data = stream_get_meta_data($fp);
foreach($meta_data['wrapper_data'] as $response) {

  /* Were we redirected? */
  if (substr(strtolower($response), 0, 10) == 'location: ') {
    /* update $url with where we were redirected to */
    $url = substr($response, 18);
  }

}

?>
]]>
   </programlisting>
  </example><!-- }}} -->

  <example xml:id="wrappers.http.example.custom.headers"> <!-- {{{ -->
   <title>Sending custom headers with an HTTP request</title>
   <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 PHP 4 and all later versions.
   </para>
   <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><!-- }}} -->
 </refsect1><!-- }}} -->

 <refsect1 role="notes"><!-- {{{ -->
  &reftitle.notes;
  <note>
   <simpara>
    HTTPS is only supported when the <link linkend="book.openssl">openssl</link>
    extension is enabled.
   </simpara>
  </note>
  <simpara>
   HTTP connections are read-only; writing data or copying
   files to an HTTP resource is not supported.
  </simpara>
 </refsect1><!-- }}} -->

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->