php.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0592e6316d3869b49637df29c471097e7bf78592 Maintainer: daijie Status: ready -->
<!-- CREDITS: Luffy, mowangjuanzi -->
<refentry xml:id="wrappers.php" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="verify_info:false" role="stream_wrapper">
 <refnamediv>
  <refname>php://</refname>
  <refpurpose>访问各个输入/输出流（I/O streams）</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>
   PHP 提供了一些杂项输入/输出（IO）流，允许访问 PHP 的输入输出流、标准输入输出和错误描述符，
   内存中、磁盘备份的临时文件流以及可以操作其他读取写入文件资源的过滤器。
  </para>

  <refsect2 xml:id="wrappers.php.std">
   <title>php://stdin, php://stdout 和 php://stderr</title>
   <simpara>
    <filename>php://stdin</filename>、<filename>php://stdout</filename> 和
    <filename>php://stderr</filename> 允许直接访问 PHP 进程相应的输入或者输出流。
    数据流引用了复制的文件描述符，所以如果你打开 <filename>php://stdin</filename> 并在之后关了它，
    仅是关闭了复制品，真正被引用的  <constant>STDIN</constant> 并不受影响。
    推荐你简单使用常量 <constant>STDIN</constant>、
    <constant>STDOUT</constant> 和 <constant>STDERR</constant> 来代替手工打开这些封装器。
   </simpara>
   <simpara>
    <filename>php://stdin</filename> 是只读的，
    <filename>php://stdout</filename> 和 <filename>php://stderr</filename> 是只写的。
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.input">
   <title>php://input</title>
   <simpara>
    <filename>php://input</filename> 是个可以访问请求的原始数据的只读流。
    如果启用了 <link linkend="ini.enable-post-data-reading">enable_post_data_reading</link> 选项，
    <filename>php://input</filename> 在使用 <literal>enctype="multipart/form-data"</literal>
    的 POST 请求中不可用。
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.output">
   <title>php://output</title>
   <para>
    <filename>php://output</filename> 是一个只写的数据流，
    允许你以 <function>print</function> 和 <function>echo</function> 一样的方式
    写入到输出缓冲区。
   </para>
  </refsect2>

  <refsect2 xml:id="wrappers.php.fd">
   <title>php://fd</title>
   <simpara>
    <filename>php://fd</filename> 允许直接访问指定的文件描述符。
    例如 <filename>php://fd/3</filename> 引用了文件描述符 3。
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.memory">
   <title>php://memory 和 php://temp</title>
   <simpara>
    <filename>php://memory</filename> 和 <filename>php://temp</filename> 是一个类似文件
    包装器的数据流，允许读写临时数据。
     
    两者的一个区别是 <filename>php://memory</filename> 总是把数据储存在内存中，
    而 <filename>php://temp</filename> 会在内存量达到预定义的限制后（默认是 2MB）存入临时文件中。
    临时文件位置的决定和 <function>sys_get_temp_dir</function> 的方式一致。
   </simpara>
   <simpara>
    <filename>php://temp</filename> 的内存限制可通过添加 <literal>/maxmemory:NN</literal> 
    来控制，<literal>NN</literal> 是以字节为单位、保留在内存的最大数据量，超过则使用临时文件。
   </simpara>
   <caution>
    <simpara>
     某些 PHP 扩展可能需要标准 IO 流，并且可能尝试将指定流转换为标准 IO
     流。对于内存流，此转换可能会失败，因为需要 C <function>fopencookie</function>
     函数可以调用。此 C 函数在 Windows 上<emphasis>无效</emphasis>。
    </simpara>
   </caution>
  </refsect2>

  <refsect2 xml:id="wrappers.php.filter">
   <title>php://filter</title>
   <simpara>
    <filename>php://filter</filename> 是一种元封装器，
    设计用于数据流打开时的<link linkend="filters">筛选过滤</link>应用。
    这对于一体式（all-in-one）的文件函数非常有用，类似 <function>readfile</function>、
    <function>file</function> 和 <function>file_get_contents</function>，
    在数据流内容读取之前没有机会应用其他过滤器。
   </simpara>
   <para>
    <filename>php://filter</filename> 目标使用以下的参数作为它路径的一部分。
    复合过滤链能够在一个路径上指定。详细使用这些参数可以参考具体范例。
   </para>
   <para>
    <table>
     <title>php://filter 参数</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>名称</entry>
        <entry>描述</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>
         <literal>resource=&lt;要过滤的数据流&gt;</literal>
        </entry>
        <entry>
         这个参数是必须的。它指定了你要筛选过滤的数据流。
        </entry>
       </row>
       <row>
        <entry>
         <literal>read=&lt;读链的筛选列表&gt;</literal>
        </entry>
        <entry>
         该参数可选。可以设定一个或多个过滤器名称，以管道符（<literal>|</literal>）分隔。
        </entry>
       </row>
       <row>
        <entry>
         <literal>write=&lt;写链的筛选列表&gt;</literal>
        </entry>
        <entry>
         该参数可选。可以设定一个或多个过滤器名称，以管道符（<literal>|</literal>）分隔。
        </entry>
       </row>
       <row>
        <entry>
         <literal>&lt;；两个链的筛选列表&gt;</literal>
        </entry>
        <entry>
         任何没有以 <literal>read=</literal> 或 <literal>write=</literal> 作前缀
         的筛选器列表会视情况应用于读或写链。
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
  </refsect2>
 </refsect1>

 <refsect1 role="options"><!-- {{{ -->
  &reftitle.options;
  <para>
   <table>
    <title>
     封装协议摘要（针对 <literal>php://filter</literal>，参考被筛选的封装器。）
    </title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>属性</entry>
       <entry>支持</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>受限于 <link linkend="ini.allow-url-fopen">allow_url_fopen</link></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>受限于 <link linkend="ini.allow-url-include">allow_url_include</link></entry>
       <entry>仅
        <literal>php://input</literal>、
        <literal>php://stdin</literal>、
        <literal>php://memory</literal> 和 
        <literal>php://temp</literal>。
       </entry>
      </row>
      <row>
       <entry>允许读取</entry>
       <entry>仅
        <literal>php://stdin</literal>、
        <literal>php://input</literal>、
        <literal>php://fd</literal>、
        <literal>php://memory</literal> 和
        <literal>php://temp</literal>。
       </entry>
      </row>
      <row>
       <entry>允许写入</entry>
       <entry>仅
        <literal>php://stdout</literal>、
        <literal>php://stderr</literal>、
        <literal>php://output</literal>、
        <literal>php://fd</literal>、
        <literal>php://memory</literal> 和
        <literal>php://temp</literal>。
       </entry>
      </row>
      <row>
       <entry>允许追加</entry>
       <entry> 仅
        <literal>php://stdout</literal>、
        <literal>php://stderr</literal>、
        <literal>php://output</literal>、
        <literal>php://fd</literal>、
        <literal>php://memory</literal> 和
        <literal>php://temp</literal>（等于写入）
       </entry>
      </row>
      <row>
       <entry>允许同时读写</entry>
       <entry>仅
        <literal>php://fd</literal>、
        <literal>php://memory</literal> 和
        <literal>php://temp</literal>。
       </entry>
      </row>
      <row>
       <entry>支持 <function>stat</function></entry>
       <entry>
        不支持。不过，<literal>php://memory</literal> 和
        <literal>php://temp</literal> 支持 <function>fstat</function>。
       </entry>
      </row>
      <row>
       <entry>支持 <function>unlink</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>支持 <function>rename</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>支持 <function>mkdir</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>支持 <function>rmdir</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>仅仅支持 <function>stream_select</function></entry>
       <entry>
        <literal>php://stdin</literal>、
        <literal>php://stdout</literal>、
        <literal>php://stderr</literal>、
        <literal>php://fd</literal> 和 
        <literal>php://temp</literal>。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1> <!-- }}} -->

 <refsect1 role="examples"><!-- {{{ -->
  &reftitle.examples;
  <example><!-- {{{ -->
   <title>php://temp/maxmemory</title>
   <para>
    这个可选选项允许设置 <filename>php://temp</filename> 开始使用临时文件前的最大内存限制。
   </para>
   <programlisting role="php">
<![CDATA[
<?php
// 限制内存为 5 MB。
$fiveMBs = 5 * 1024 * 1024;
$fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

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

// 读取刚才写入的内容。
rewind($fp);
echo stream_get_contents($fp);
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/resource=&lt;待过滤的数据流&gt;</title>
   <para>
    这个参数必须位于 <filename>php://filter</filename> 的末尾，并且指向需要过滤筛选的数据流。
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* 这简单等同于：
  readfile("http://www.example.com");
  实际上没有指定过滤器 */

readfile("php://filter/resource=http://www.example.com");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/read=&lt;读链需要应用的过滤器列表&gt;</title>
   <para>
    这个参数采用一个或以管道符 <literal>|</literal> 分隔的多个过滤器名称。
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* 这会以大写字母输出 www.example.com 的全部内容 */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");

/* 这会和以上所做的一样，但还会用 ROT13 加密。 */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/write=&lt;写链需要应用的过滤器列表&gt;</title>
   <para>
    这个参数采用一个或以管道符 <literal>|</literal> 分隔的多个过滤器名称。
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* 这会通过 rot13 过滤器筛选出字符 "Hello World"
  然后写入当前目录下的 example.txt */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example>
   <title>php://memory 和 php://temp 是一次性的</title>
   <para>
    <filename>php://memory</filename> 和 <filename>php://temp</filename>
    是一次性的，比如：stream 流关闭后，就无法再次得到以前的内容了。
   </para>
   <programlisting role="php">
<![CDATA[
<?php
file_put_contents('php://memory', 'PHP');
echo file_get_contents('php://memory'); // 啥也没有
]]>
   </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
-->