php-doc-en/language/wrappers/php.xml

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

<refentry xml:id="wrappers.php" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
 <refnamediv>
  <refname>PHP input/output</refname>
  <refpurpose>Accessing various I/O streams</refpurpose>
 </refnamediv>

 <refsect1 role="description"><!-- {{{ -->
  &reftitle.description;
  <para>
   <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.
  </para>
  <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 data
   from the request body.
   In case of POST requests, it preferrable to
   <varname>$HTTP_RAW_POST_DATA</varname> as it does not depend on
   special &php.ini; directives. Moreover, for those cases where
   <varname>$HTTP_RAW_POST_DATA</varname> is not populated by
   default, it is a potentially less memory intensive alternative
   to activating <link linkend="ini.always-populate-raw-post-data">always_populate_raw_post_data</link>.
   <filename>php://input</filename> is not available with
   <literal>enctype="multipart/form-data"</literal>.
  </simpara>
  <note>
   <simpara>
    A stream opened with <filename>php://input</filename> can only be read
    once; the stream does not support seek operations. However, depending
    on the SAPI implementation, it may be possible to open another
    <filename>php://input</filename> stream and restart reading. This is
    only possible if the request body data has been saved. Typically, this
    is the case for POST requests, but not other request methods, such as
    PUT or PROPFIND.
   </simpara>
  </note>
  <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>
 </refsect1><!-- }}} -->

 <refsect1 role="usage"> <!-- {{{ -->
  &reftitle.options;
  <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>
 </refsect1> <!-- }}} -->

 <refsect1 role="options"><!-- {{{ -->
  &reftitle.options;
  <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>
 </refsect1> <!-- }}} -->

 <refsect1 role="examples"><!-- {{{ -->
  &reftitle.examples;
  <example><!-- {{{ -->
   <title>/resource=&lt;stream to be filtered&gt; (<emphasis>required</emphasis>)</title>
   <para>
    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.
   </para>
   <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>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>/read=&lt;filter list to apply to read chain&gt; (<emphasis>optional</emphasis>)</title>
   <para>
    This parameter takes one or more
    filternames separated by the pipe character <literal>|</literal>.
   </para>
   <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>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>/write=&lt;filter list to apply to write chain&gt; (<emphasis>optional</emphasis>)</title>
   <para>
    This parameter takes one or more
    filternames separated by the pipe character <literal>|</literal>.
   </para>
   <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>
  </example><!-- }}} -->
  <!-- {{{ -->
  <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>

  <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>
  <!-- }}} -->
  <example><!-- {{{ -->
   <title>/maxmemory:&lt;number of bytes&gt; (<emphasis>optional</emphasis>)</title>
   <para>
    This parameter allows changing the
    default value for the memory limit (when the data is moved to a temporary
    file).
   </para>
   <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>
  </example><!-- }}} -->
 </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
-->