<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297557 $ -->
<appendix xml:id="wrappers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>List of Supported Protocols/Wrappers</title>
 <para>
  PHP comes with many built-in wrappers for various URL-style protocols 
  for use with the filesystem functions such as <function>fopen</function> 
  and <function>copy</function>. In addition to these wrappers, you can as of 
  PHP 4.3.0, write your own wrappers using the <function>stream_wrapper_register</function> 
  function.
 </para>
  <note>
   <simpara>The URL syntax used to describe a wrapper only supports the scheme://... syntax.  
            scheme:/ and scheme: syntaxes are not supported.
   </simpara>
  </note>
 <para>
  List of context options is available in the chapter <xref linkend="context"/>.
 </para>

 <section xml:id="wrappers.file">
  <title>Filesystem</title>
  <simpara>All versions of PHP. Explicitly using <filename>file://</filename> since PHP 5.0.0.</simpara>

  <itemizedlist>
   <listitem><simpara><filename>/path/to/file.ext</filename></simpara></listitem>
   <listitem><simpara><filename>relative/path/to/file.ext</filename></simpara></listitem>
   <listitem><simpara><filename>fileInCwd.ext</filename></simpara></listitem>
   <listitem><simpara><filename>C:/path/to/winfile.ext</filename></simpara></listitem>
   <listitem><simpara><filename>C:\path\to\winfile.ext</filename></simpara></listitem>
   <listitem><simpara><filename>\\smbserver\share\path\to\winfile.ext</filename></simpara></listitem>
   <listitem><simpara><filename>file:///path/to/file.ext</filename></simpara></listitem>
  </itemizedlist>

  <simpara>
   <emphasis>Filesystem</emphasis> is the default wrapper used with PHP and represents the local filesystem.
   When a relative path is specified (a path which does not begin with /, \, \\, or a Windows drive letter)
   the path provided will be applied against the current working directory.  In many cases this is the
   directory in which the script resides unless it has been changed.  Using the CLI sapi, this defaults
   to the directory from which the script was called.
  </simpara>

  <simpara>
   With some functions, such as <function>fopen</function> and <function>file_get_contents</function>,
   <literal>include_path</literal> may be optionally searched for relative paths as well.
  </simpara>

  <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>No</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>stat</function></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>unlink</function></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>rename</function></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>mkdir</function></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>rmdir</function></entry>
       <entry>Yes</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>

 <!-- FIXME PHP_6 Mentioned PHP 6, but let's explore not hard coding PHP versions like this -->
 <section xml:id="wrappers.http">
  <title>HTTP and HTTPS</title>
   <simpara>PHP 4, PHP 5. <filename>https://</filename> since PHP 4.3.0</simpara>

  <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>

  <simpara>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.
  </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>
  <informalexample>
   <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>
  </informalexample>
  <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>
  <simpara>
   HTTP connections are read-only; you cannot write data or copy
   files to an HTTP resource.
  </simpara>
  <note>
   <simpara>HTTPS is supported starting from PHP 4.3.0, if you
    have compiled in support for OpenSSL.
   </simpara>
  </note>
  <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>
  <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>

  <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>
  <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>

 <!-- FIXME PHP_6 Mentioned PHP 6, but let's explore not hard coding PHP versions like this -->
 <section xml:id="wrappers.ftp">
  <title>FTP and FTPS</title>
  <simpara>PHP 4, PHP 5.  <filename>ftps://</filename> since PHP 4.3.0</simpara>

  <itemizedlist>
   <listitem><simpara><filename>ftp://example.com/pub/file.txt</filename></simpara></listitem>
   <listitem><simpara><filename>ftp://user:password@example.com/pub/file.txt</filename></simpara></listitem>
   <listitem><simpara><filename>ftps://example.com/pub/file.txt</filename></simpara></listitem>
   <listitem><simpara><filename>ftps://user:password@example.com/pub/file.txt</filename></simpara></listitem>
  </itemizedlist>

  <simpara>
   Allows read access to existing files and creation of new files
   via FTP.  If the server does not support passive mode ftp, the
   connection will fail.
  </simpara>
  <simpara>
   You can open files for either reading or writing, but not both
   simultaneously.  If the remote file already exists on the ftp
   server and you attempt to open it for writing but have not specified
   the context option <literal>overwrite</literal>, the connection
   will fail.  If you need to overwrite existing files over ftp,
   specify the <literal>overwrite</literal> option in the context
   and open the file for writing.  Alternatively, you can
   use the <link linkend="ref.ftp">FTP extension</link>.
  </simpara>
  <note>
   <title>Appending</title>
   <simpara>
    As of PHP 5.0.0 files may be appended via the
    <literal>ftp://</literal> URL wrapper.  In prior versions, attempting
    to append to a file via <literal>ftp://</literal> will result in failure.
   </simpara>
  </note>
  <simpara>
   <filename>ftps://</filename> was introduced in PHP 4.3.0.
   It is the same as <filename>ftp://</filename>,
   but attempts to negotiate a secure connection with the ftp server.
   If the server does not support SSL, then the connection falls back
   to regular unencrypted ftp.
  </simpara>
  <note>
   <simpara>FTPS is supported starting from PHP 4.3.0, if you
    have compiled in support for OpenSSL.
   </simpara>
  </note>
  <simpara>
   If you have set the <link linkend="ini.from">from</link> directive
   in &php.ini;, then this value will be sent as the anonymous FTP
   password.
  </simpara>
  <para>
   <table>
    <title>Wrapper Summary</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Attribute</entry>
       <entry>PHP 4</entry>
       <entry>PHP 5</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link></entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>Yes (new files only)</entry>
       <entry>Yes (new files/existing files with <parameter>overwrite</parameter>)</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>No</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>No</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>stat</function></entry>
       <entry>No</entry>
       <entry>
        As of PHP 5.0.0: <function>filesize</function>,
        <function>filetype</function>, <function>file_exists</function>,
        <function>is_file</function>, and <function>is_dir</function> elements only.
        As of PHP 5.1.0: <function>filemtime</function>.
       </entry>
      </row>
      <row>
       <entry>Supports <function>unlink</function></entry>
       <entry>No</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>rename</function></entry>
       <entry>No</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>mkdir</function></entry>
       <entry>No</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>rmdir</function></entry>
       <entry>No</entry>
       <entry>Yes</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>

 <section xml:id="wrappers.php">
  <title>PHP input/output streams</title>

  <itemizedlist>
   <listitem><simpara><filename>php://stdin</filename></simpara></listitem>
   <listitem><simpara><filename>php://stdout</filename></simpara></listitem>
   <listitem><simpara><filename>php://stderr</filename></simpara></listitem>
   <listitem><simpara><filename>php://output</filename></simpara></listitem>
   <listitem><simpara><filename>php://input</filename></simpara></listitem>
   <listitem><simpara><filename>php://filter</filename> (available since PHP 5.0.0)</simpara></listitem>
   <listitem><simpara><filename>php://memory</filename> (available since PHP 5.1.0)</simpara></listitem>
   <listitem><simpara><filename>php://temp</filename> (available since PHP 5.1.0)</simpara></listitem>
  </itemizedlist>

  <simpara>
   <filename>php://stdin</filename>, <filename>php://stdout</filename>
   and <filename>php://stderr</filename> allow direct access to
   the corresponding input or output stream of the PHP process.  The stream
   references a duplicate file descriptor, so if you open
   <filename>php://stdin</filename> and later close it, you close only your
   copy of the descriptor--the actual stream referenced by
   <constant>STDIN</constant> is unaffected.  Note that PHP exhibited buggy
   behavior in this regard until PHP 5.2.1.  It is recommended that you simply
   use the constants <constant>STDIN</constant>, <constant>STDOUT</constant>
   and <constant>STDERR</constant> instead of manually opening streams using
   these wrappers.
  </simpara>
  <simpara>
   <filename>php://output</filename> allows you to write to the
   output buffer mechanism in the same way as
   <function>print</function> and <function>echo</function>.
  </simpara>
  <simpara>
   <filename>php://input</filename> allows you to read raw POST data.
   It is a less memory intensive alternative to
   <varname>$HTTP_RAW_POST_DATA</varname> and does not need any
   special &php.ini; directives.
   <filename>php://input</filename> is not available with
   <literal>enctype="multipart/form-data"</literal>.
  </simpara>
  <simpara>
   <filename>php://stdin</filename> and
   <filename>php://input</filename> are read-only, whereas
   <filename>php://stdout</filename>,
   <filename>php://stderr</filename> and
   <filename>php://output</filename> are write-only.
  </simpara>

  <simpara>
   <filename>php://filter</filename> is a kind of meta-wrapper designed
   to permit the application of filters to a stream at the time of
   opening.  This is useful with all-in-one file functions such as
   <function>readfile</function>, <function>file</function>, and
   <function>file_get_contents</function> where there is otherwise
   no opportunity to apply a filter to the stream prior the contents
   being read.
  </simpara>
  <simpara>
   The <filename>php://filter</filename> target takes the following
   'parameters' as parts of its 'path'.
  </simpara>
  <itemizedlist>
   <listitem>
    <para>
     <literal>/resource=&lt;stream to be filtered&gt;</literal>
     (<emphasis>required</emphasis>)  This parameter must be located at
     the end of your <filename>php://filter</filename> specification and
     should point to the stream which you want filtered.
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
/* This is equivalent to simply:
   readfile("http://www.example.com");
   since no filters are actually specified */

readfile("php://filter/resource=http://www.example.com");
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </listitem>
   <listitem>
    <para>
     <literal>/read=&lt;filter list to apply to read chain&gt;</literal>
     (<emphasis>optional</emphasis>)  This parameter takes one or more
     filternames separated by the pipe character <literal>|</literal>.
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
/* This will output the contents of
   www.example.com entirely in uppercase */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");

/* This will do the same as above
   but will also ROT13 encode it */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </listitem>
   <listitem>
    <para>
     <literal>/write=&lt;filter list to apply to write chain&gt;</literal>
     (<emphasis>optional</emphasis>)  This parameter takes one or more
     filternames separated by the pipe character <literal>|</literal>.
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
/* This will filter the string "Hello World"
   through the rot13 filter, then write to
   example.txt in the current directory */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </listitem>
   <listitem>
    <simpara>
     <literal>/&lt;filter list to apply to both chains&gt;</literal>
     (<emphasis>optional</emphasis>)  Any filter lists which are not
     prefixed specifically by <literal>read=</literal> or
     <literal>write=</literal> will be applied to both the read and
     write chains (as appropriate).
    </simpara>
   </listitem>
  </itemizedlist>

  <simpara>
   The <filename>php://memory</filename> wrapper stores the data in the
   memory. <filename>php://temp</filename> behaves similarly, but uses a
   temporary file for storing the data when a certain memory limit is reached
   (the default is 2 MB).
  </simpara>
  <simpara>
   The <filename>php://temp</filename> wrapper takes the following
   'parameters' as parts of its 'path':
  </simpara>
  <itemizedlist>
   <listitem>
    <para>
     <literal>/maxmemory:&lt;number of bytes&gt;</literal>
     (<emphasis>optional</emphasis>). This parameter allows changing the
     default value for the memory limit (when the data is moved to a temporary
     file).
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
$fiveMBs = 5 * 1024 * 1024;
$fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

fputs($fp, "hello\n");

// read what we have written
rewind($fp);
echo stream_get_contents($fp);
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </listitem>
  </itemizedlist>

  <para>
   <table>
    <title>
     Wrapper Summary (For <literal>php://filter</literal>,
     refer to summary of wrapper being filtered.)
    </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>No</entry>
      </row>
      <row>
       <entry>Restricted by <link linkend="ini.allow-url-include">allow_url_include</link></entry>
       <entry>
        <literal>php://input</literal>,
        <literal>php://stdin</literal>,
        <literal>php://memory</literal> and
        <literal>php://temp</literal> only.
       </entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>
        <literal>php://stdin</literal>,
        <literal>php://input</literal>,
        <literal>php://memory</literal> and
        <literal>php://temp</literal> only.
       </entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>
        <literal>php://stdout</literal>,
        <literal>php://stderr</literal>,
        <literal>php://output</literal>,
        <literal>php://memory</literal> and
        <literal>php://temp</literal> only.
       </entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>
        <literal>php://stdout</literal>,
        <literal>php://stderr</literal>,
        <literal>php://output</literal>,
        <literal>php://memory</literal> and
        <literal>php://temp</literal> only. (Equivalent to writing)
       </entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>
        <literal>php://memory</literal> and
        <literal>php://temp</literal> only.
       </entry>
      </row>
      <row>
       <entry>Supports <function>stat</function></entry>
       <entry>
        <literal>php://memory</literal> and
        <literal>php://temp</literal> only.
       </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>
      <row>
       <entry>Supports <function>stream_select</function></entry>
       <entry>
        <literal>php://stdin</literal>, <literal>php://stdout</literal>, 
        <literal>php://stderr</literal> and <literal>php://temp</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>

 <section xml:id="wrappers.compression">
  <title>Compression Streams</title>
  <simpara><filename>zlib:</filename> PHP 4.0.4 - PHP 4.2.3 (systems with fopencookie only)</simpara>
  <simpara><filename>compress.zlib://</filename> and <filename>compress.bzip2://</filename> PHP 4.3.0 and up</simpara>

  <itemizedlist>
   <listitem><simpara><filename>zlib:</filename></simpara></listitem>
   <listitem><simpara><filename>compress.zlib://</filename></simpara></listitem>
   <listitem><simpara><filename>compress.bzip2://</filename></simpara></listitem>
  </itemizedlist>

  <simpara>
   <filename>zlib:</filename> works like <function>gzopen</function>, except that the
   stream can be used with <function>fread</function> and the other
   filesystem functions.  This is deprecated as of PHP 4.3.0 due
   to ambiguities with filenames containing ':' characters; use
   <filename>compress.zlib://</filename> instead.
  </simpara>

  <simpara>
   <filename>compress.zlib://</filename> and
   <filename>compress.bzip2://</filename> are equivalent to
   <function>gzopen</function> and <function>bzopen</function>
   respectively, and operate even on systems that do not support
   fopencookie.
  </simpara>
  <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>No</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>stat</function></entry>
       <entry>
        No, use the normal <literal>file://</literal> wrapper
        to stat compressed files.
       </entry>
      </row>
      <row>
       <entry>Supports <function>unlink</function></entry>
       <entry>
        No, use the normal <literal>file://</literal> wrapper
        to unlink compressed files.
       </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>
  <para>
   <link linkend="book.zip">ZIP extension</link> registers <filename>zip:</filename> wrapper.
  </para>
 </section>

 <section xml:id="wrappers.data">
  <title>Data (RFC 2397)</title>
  <simpara>
   The <filename>data:</filename> (<link xlink:href="&url.rfc;2397">RFC
   2397</link>) stream wrapper is available since PHP 5.2.0.
  </simpara>

  <example>
   <title>Print data:// contents</title>
   <programlisting role="php">
<![CDATA[
<?php
// prints "I love PHP"
echo file_get_contents('data://text/plain;base64,SSBsb3ZlIFBIUAo=');
?>
]]>
   </programlisting>
  </example>

  <example>
   <title>Fetch the media type</title>
   <programlisting role="php">
<![CDATA[
<?php
$fp   = fopen('data://text/plain;base64,', 'r');
$meta = stream_get_meta_data($fp);

// prints "text/plain"
echo $meta['mediatype'];
?>
]]>
   </programlisting>
  </example>


  <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>No</entry>
      </row>
      <row>
       <entry>Restricted by <link linkend="ini.allow-url-include">allow_url_include</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>No</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>
 </section>

 <section xml:id="wrappers.glob">
  <title>Glob</title>
  <simpara>
   The <filename>glob:</filename> stream wrapper is available since PHP 5.3.0.
  </simpara>

  <example>
   <title>Basic usage</title>
   <programlisting role="php">
<![CDATA[
<?php
// Loop over all *.php files in ext/spl/examples/ directory
// and print the filename and its size
$it = new DirectoryIterator("glob://ext/spl/examples/*.php");
foreach($it as $f) {
    printf("%s: %.1FK\n", $f->getFilename(), $f->getSize()/1024);
}
?>
]]>
   </programlisting>
   <screen>
<![CDATA[
tree.php: 1.0K
findregex.php: 0.6K
findfile.php: 0.7K
dba_dump.php: 0.9K
nocvsdir.php: 1.1K
phar_from_dir.php: 1.0K
ini_groups.php: 0.9K
directorytree.php: 0.9K
dba_array.php: 1.1K
class_tree.php: 1.8K
]]>
   </screen>
  </example>

  <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>No</entry>
      </row>
      <row>
       <entry>Restricted by <link linkend="ini.allow-url-include">allow_url_include</link></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>No</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>No</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>
 </section>


 <section xml:id="wrappers.phar">
  <title>Phar</title>
  <simpara>
   The <filename>phar://</filename> stream wrapper is available since
   PHP 5.3.0. See <link linkend="phar.using.stream">Phar stream wrapper</link>
   for detailed description.
  </simpara>

  <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>No</entry>
      </row>
      <row>
       <entry>Restricted by <link linkend="ini.allow-url-include">allow_url_include</link></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>stat</function></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>unlink</function></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>rename</function></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>mkdir</function></entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Supports <function>rmdir</function></entry>
       <entry>Yes</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>


 <section xml:id="wrappers.ssh2">
  <title>Secure Shell 2</title>
  <simpara>
   <filename>ssh2.shell://</filename>
   <filename>ssh2.exec://</filename>
   <filename>ssh2.tunnel://</filename>
   <filename>ssh2.sftp://</filename>
   <filename>ssh2.scp://</filename>
   PHP 4.3.0 and up (PECL)
  </simpara>

  <itemizedlist>
   <listitem><simpara><filename>ssh2.shell://user:pass@example.com:22/xterm</filename></simpara></listitem>
   <listitem><simpara><filename>ssh2.exec://user:pass@example.com:22/usr/local/bin/somecmd</filename></simpara></listitem>
   <listitem><simpara><filename>ssh2.tunnel://user:pass@example.com:22/192.168.0.1:14</filename></simpara></listitem>
   <listitem><simpara><filename>ssh2.sftp://user:pass@example.com:22/path/to/filename</filename></simpara></listitem>
  </itemizedlist>

  <note>
   <title>This wrapper is not enabled by default</title>
   <simpara>
    In order to use the <filename>ssh2.*://</filename> wrappers you must install
    the <link xlink:href="&url.pecl.package;ssh2">SSH2</link> extension
    available from <link xlink:href="&url.pecl;">PECL</link>.
   </simpara>
  </note>

  <simpara>
   In addition to accepting traditional URI login details, the ssh2 wrappers
   will also reuse open connections by passing the connection resource in the
   host portion of the URL.
  </simpara>

  <example>
   <title>Opening a stream from an active connection</title>
   <programlisting role="php">
<![CDATA[
<?php
$session = ssh2_connect('example.com', 22);
ssh2_auth_pubkey_file($session, 'username', '/home/username/.ssh/id_rsa.pub',
                                            '/home/username/.ssh/id_rsa', 'secret');
$stream = fopen("ssh2.tunnel://$session/remote.example.com:1234", 'r');
?>
]]>
   </programlisting>
  </example>
  <para>
   <table>
    <title>Wrapper Summary</title>
    <tgroup cols="6">
     <thead>
      <row>
       <entry>Attribute</entry>
       <entry>ssh2.shell</entry>
       <entry>ssh2.exec</entry>
       <entry>ssh2.tunnel</entry>
       <entry>ssh2.sftp</entry>
       <entry>ssh2.scp</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Restricted by <link linkend="ini.allow-url-fopen">allow_url_fopen</link></entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>Yes (When supported by server)</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>Yes</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>stat</function></entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>Yes</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>unlink</function></entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>Yes</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>rename</function></entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>Yes</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>mkdir</function></entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>Yes</entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Supports <function>rmdir</function></entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>No</entry>
       <entry>Yes</entry>
       <entry>No</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>

  <para>
   <table>
    <title>Context options</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Name</entry>
       <entry>Usage</entry>
       <entry>Default</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>session</literal></entry>
       <entry>Preconnected ssh2 resource to be reused</entry>
       <entry/>
      </row>
      <row>
       <entry><literal>sftp</literal></entry>
       <entry>Preallocated sftp resource to be reused</entry>
       <entry/>
      </row>
      <row>
       <entry><literal>methods</literal></entry>
       <entry>Key exchange, hostkey, cipher, compression, and MAC methods to use</entry>
       <entry/>
      </row>
      <row>
       <entry><literal>callbacks</literal></entry>
       <entry></entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>username</literal></entry>
       <entry>Username to connect as</entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>password</literal></entry>
       <entry>Password to use with password authentication</entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>pubkey_file</literal></entry>
       <entry>Name of public key file to use for authentication</entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>privkey_file</literal></entry>
       <entry>Name of private key file to use for authentication</entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>env</literal></entry>
       <entry>Associate array of environment variables to set</entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>term</literal></entry>
       <entry>Terminal emulation type to request when allocating a pty</entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>term_width</literal></entry>
       <entry>Width of terminal requested when allocating a pty</entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>term_height</literal></entry>
       <entry>Height of terminal requested when allocating a pty</entry>
       <entry></entry>
      </row>
      <row>
       <entry><literal>term_units</literal></entry>
       <entry>Units to use with term_width and term_height</entry>
       <entry><constant>SSH2_TERM_UNIT_CHARS</constant></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>


 </section>

 <section xml:id="wrappers.audio">
  <title>Audio Streams</title>
  <simpara><filename>ogg://</filename> PHP 4.3.0 and up (PECL) </simpara>

  <itemizedlist>
   <listitem><simpara><filename>ogg://soundfile.ogg</filename></simpara></listitem>
   <listitem><simpara><filename>ogg:///path/to/soundfile.ogg</filename></simpara></listitem>
   <listitem><simpara><filename>ogg://http://www.example.com/path/to/soundstream.ogg</filename></simpara></listitem>
  </itemizedlist>

  <note>
   <title>This wrapper is not enabled by default</title>
   <simpara>
    In order to use the <filename>ogg://</filename> wrapper you must install
    the <link xlink:href="&url.pecl.package;oggvorbis">OGG/Vorbis</link> extension
    available from <link xlink:href="&url.pecl;">PECL</link>.
   </simpara>
  </note>

  <simpara>
   Files opened for reading via the <filename>ogg://</filename> wrapper
   are treated as compressed audio encoded using the <literal>OGG/Vorbis</literal> codec.
   Similarly, files opened for writing or appending via the
   <filename>ogg://</filename> wrapper are writen as compressed audio data.
   <function>stream_get_meta_data</function>, when used on an <literal>OGG/Vorbis</literal>
   file opened for reading will return various details about the stream
   including the <parameter>vendor</parameter> tag, any included
   <parameter>comments</parameter>, the number of
   <parameter>channels</parameter>, the sampling <parameter>rate</parameter>,
   and the encoding rate range described by:
   <parameter>bitrate_lower</parameter>, <parameter>bitrate_upper</parameter>,
   <parameter>bitrate_nominal</parameter>, and <parameter>bitrate_window</parameter>.
  </simpara>

  <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>No</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>No</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>
  <para>
   <table>
    <title>Context options</title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Name</entry>
       <entry>Usage</entry>
       <entry>Default</entry>
       <entry>Mode</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>pcm_mode</literal></entry>
       <entry>
        PCM encoding to apply while reading, one of:
        <constant>OGGVORBIS_PCM_U8</constant>, <constant>OGGVORBIS_PCM_S8</constant>,
        <constant>OGGVORBIS_PCM_U16_BE</constant>, <constant>OGGVORBIS_PCM_S16_BE</constant>,
        <constant>OGGVORBIS_PCM_U16_LE</constant>, and <constant>OGGVORBIS_PCM_S16_LE</constant>.
        (8 vs 16 bit, signed or unsigned, big or little <literal>endian</literal>)
       </entry>
       <entry>OGGVORBIS_PCM_S16_LE</entry>
       <entry>Read</entry>
      </row>
      <row>
       <entry><literal>rate</literal></entry>
       <entry>
        Sampling rate of input data, expressed in Hz
       </entry>
       <entry>44100</entry>
       <entry>Write/Append</entry>
      </row>
      <row>
       <entry><literal>bitrate</literal></entry>
       <entry>
        When given as an integer, the fixed bitrate at which to encode. (16000 to 131072)
        When given as a float, the variable bitrate quality to use. (-1.0 to 1.0)
       </entry>
       <entry>128000</entry>
       <entry>Write/Append</entry>
      </row>
      <row>
       <entry><literal>channels</literal></entry>
       <entry>
        The number of audio channels to encode, typically 1 (Mono), or 2 (Stero).
        May range as high as 16.
       </entry>
       <entry>2</entry>
       <entry>Write/Append</entry>
      </row>
      <row>
       <entry><literal>comments</literal></entry>
       <entry>
        An array of string values to encode into the track header.
       </entry>
       <entry/>
       <entry>Write/Append</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </section>


 <section xml:id="wrappers.expect">
  <title>Process Interaction Streams</title>
  <simpara><filename>expect://</filename> PHP 4.3.0 and up (PECL) </simpara>

  <itemizedlist>
   <listitem><simpara><filename>expect://command</filename></simpara></listitem>
  </itemizedlist>

  <note>
   <title>This wrapper is not enabled by default</title>
   <simpara>
    In order to use the <filename>expect://</filename> wrapper you must install
    the <link xlink:href="&url.pecl.package;expect">Expect</link> extension
    available from <link xlink:href="&url.pecl;">PECL</link>.
   </simpara>
  </note>

  <simpara>
   Streams opened via the <filename>expect://</filename> wrapper provide
   access to process'es stdio, stdout and stderr via PTY.
  </simpara>

  <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>No</entry>
      </row>
      <row>
       <entry>Allows Reading</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Writing</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Appending</entry>
       <entry>Yes</entry>
      </row>
      <row>
       <entry>Allows Simultaneous Reading and Writing</entry>
       <entry>No</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>
 </section>

</appendix>

<!-- 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
-->