php-doc-en/language/wrappers/php.xml
Peter Cowburn ea8575f778 add ids for wrappers refsects
To address the problem of HTML ids (for permalinks) like:
refsect2-wrappers.php-unknown-unknown-unknown-unknown-unknown-descriptios

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@343104 c90b9560-bf6c-de11-be94-00142212c4b1
2017-09-18 19:19:12 +00:00

444 lines
14 KiB
XML

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="wrappers.php" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" role="noversion">
<refnamediv>
<refname>php://</refname>
<refpurpose>Accessing various I/O streams</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>
PHP provides a number of miscellaneous I/O streams that allow access to
PHP's own input and output streams, the standard input, output and error
file descriptors, in-memory and disk-backed temporary file streams, and
filters that can manipulate other file resources as they are read from and
written to.
</para>
<refsect2 xml:id="wrappers.php.std">
<title>php://stdin, php://stdout and php://stderr</title>
<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://stdin</filename> is read-only, whereas
<filename>php://stdout</filename> and <filename>php://stderr</filename> are
write-only.
</simpara>
</refsect2>
<refsect2 xml:id="wrappers.php.input">
<title>php://input</title>
<simpara>
<filename>php://input</filename> is a read-only stream that allows you to
read raw data from the request body. In the case of POST requests, it is
preferable to use <filename>php://input</filename> instead of <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>
Prior to PHP 5.6, a stream opened with <filename>php://input</filename>
could only be read once; the stream did 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>
</refsect2>
<refsect2 xml:id="wrappers.php.output">
<title>php://output</title>
<para>
<filename>php://output</filename> is a write-only stream that allows you to
write to the output buffer mechanism in the same way as
<function>print</function> and <function>echo</function>.
</para>
</refsect2>
<refsect2 xml:id="wrappers.php.fd">
<title>php://fd</title>
<simpara>
<filename>php://fd</filename> allows direct access to the given file
descriptor. For example, <filename>php://fd/3</filename> refers to file
descriptor 3.
</simpara>
</refsect2>
<refsect2 xml:id="wrappers.php.memory">
<title>php://memory and php://temp</title>
<simpara>
<filename>php://memory</filename> and <filename>php://temp</filename> are
read-write streams that allow temporary data to be stored in a file-like
wrapper. The only difference between the two is that
<filename>php://memory</filename> will always store its data in memory,
whereas <filename>php://temp</filename> will use a temporary file once the
amount of data stored hits a predefined limit (the default is 2 MB). The
location of this temporary file is determined in the same way as the
<function>sys_get_temp_dir</function> function.
</simpara>
<simpara>
The memory limit of <filename>php://temp</filename> can be controlled by
appending <literal>/maxmemory:NN</literal>, where <literal>NN</literal> is
the maximum amount of data to keep in memory before using a temporary
file, in bytes.
</simpara>
</refsect2>
<refsect2 xml:id="wrappers.php.filter">
<title>php://filter</title>
<simpara>
<filename>php://filter</filename> is a kind of meta-wrapper designed to
permit the application of <link linkend="filters">filters</link> 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>
<para>
The <filename>php://filter</filename> target takes the following parameters
as part of its path. Multiple filter chains can be specified on one path.
Please refer to the examples for specifics on using these parameters.
</para>
<para>
<table>
<title>php://filter parameters</title>
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<literal>resource=&lt;stream to be filtered&gt;</literal>
</entry>
<entry>
This parameter is required. It specifies the stream that you would
like to filter.
</entry>
</row>
<row>
<entry>
<literal>read=&lt;filter list to apply to read chain&gt;</literal>
</entry>
<entry>
This parameter is optional. One or more filter names can be provided
here, separated by the pipe character (<literal>|</literal>).
</entry>
</row>
<row>
<entry>
<literal>write=&lt;filter list to apply to write chain&gt;</literal>
</entry>
<entry>
This parameter is optional. One or more filter names can be provided
here, separated by the pipe character (<literal>|</literal>).
</entry>
</row>
<row>
<entry>
<literal>&lt;filter list to apply to both chains&gt;</literal>
</entry>
<entry>
Any filter lists which are not prefixed by <literal>read=</literal>
or <literal>write=</literal> will be applied to both the read and
write chains as appropriate.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</refsect2>
</refsect1>
<refsect1 role="options"><!-- {{{ -->
&reftitle.options;
<para>
<table>
<title>
Wrapper Summary (for <literal>php://filter</literal>, refer to the
summary of the 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://fd</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://fd</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://fd</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://fd</literal>,
<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>,
<literal>php://fd</literal> and
<literal>php://temp</literal> only.
</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>5.6.0</entry>
<entry>
<filename>php://input</filename> was made reusable.
</entry>
</row>
<row>
<entry>5.3.6</entry>
<entry>
<filename>php://fd</filename> was added.
</entry>
</row>
<row>
<entry>5.1.0</entry>
<entry>
<filename>php://memory</filename> and <filename>php://temp</filename>
were added.
</entry>
</row>
<row>
<entry>5.0.0</entry>
<entry>
<filename>php://filter</filename> was added.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1><!-- }}} -->
<refsect1 role="examples"><!-- {{{ -->
&reftitle.examples;
<example><!-- {{{ -->
<title>php://temp/maxmemory</title>
<para>
This optional parameter allows setting the memory limit before
<filename>php://temp</filename> starts using a temporary file.
</para>
<programlisting role="php">
<![CDATA[
<?php
// Set the limit to 5 MB.
$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><!-- }}} -->
<example><!-- {{{ -->
<title>php://filter/resource=&lt;stream to be filtered&gt;</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>php://filter/read=&lt;filter list to apply to read chain&gt;</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>php://filter/write=&lt;filter list to apply to write chain&gt;</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><!-- }}} -->
<example>
<title>php://memory and php://temp are not reusable</title>
<para>
<filename>php://memory</filename> and <filename>php://temp</filename>
are not reusable, i.e. after the streams have been closed there is no way
to refer to them again.
</para>
<programlisting role="php">
<![CDATA[
file_put_contents('php://memory', 'PHP');
echo file_get_contents('php://memory'); // prints nothing
]]>
</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
-->