mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
1028f91a84
- Added an introduction separate to the description of the individual wrappers. - Used refsect2 elements to add more hierarchy to the description of the wrappers and make it more obvious which parts of the description match to which wrappers. - Separated the examples out from the description fully (there were bits of description dangling between examples, presumably from an earlier refactor). - Removed the now-extraneous option listing. - Added documentation for php://filter's parameters separate from the examples. - Linked to the filters page. This also fixes doc bug #54228 (PHP I/O doc page does not describe all options), which was why I actually started looking at this in the first place. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@312157 c90b9560-bf6c-de11-be94-00142212c4b1
422 lines
13 KiB
XML
422 lines
13 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>
|
|
<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>
|
|
<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 <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>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<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>
|
|
<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>
|
|
<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).
|
|
</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>
|
|
<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. 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=<stream to be filtered></literal>
|
|
</entry>
|
|
<entry>
|
|
This parameter is required. It specifies the stream that you would
|
|
like to filter.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>read=<filter list to apply to read chain></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=<filter list to apply to write chain></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><filter list to apply to both chains></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.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=<stream to be filtered></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=<filter list to apply to read chain></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=<filter list to apply to write chain></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><!-- }}} -->
|
|
</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
|
|
-->
|
|
|