php.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 0592e6316d3869b49637df29c471097e7bf78592 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<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>Acceso a los diversos flujos I/O</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>
   PHP proporciona un número importante de flujos I/O que permiten acceder
   a los flujos de entrada y salida de PHP mismo, a los descriptores de ficheros
   de entrada, salida y error estándar, a flujos que representan
   ficheros temporales en memoria viva o en disco, así como a filtros
   que pueden manipular otros recursos de ficheros durante la lectura o escritura.
  </para>

  <refsect2 xml:id="wrappers.php.std">
   <title>php://stdin, php://stdout y php://stderr</title>
   <simpara>
    <filename>php://stdin</filename>, <filename>php://stdout</filename> y
    <filename>php://stderr</filename> permiten acceso directo a los flujos de entrada
    o salida correspondientes del proceso PHP. El flujo hace referencia a una copia
    del descriptor de fichero, lo que significa que si se abre <filename>php://stdin</filename>
    y se cierra más tarde, solo se cierra la copia del descriptor; el
    flujo realmente referenciado por <constant>STDIN</constant> no se ve afectado.
    Se recomienda utilizar únicamente las constantes <constant>STDIN</constant>,
    <constant>STDOUT</constant> y <constant>STDERR</constant> en lugar
    de abrir manualmente los flujos utilizando estas envolturas.
   </simpara>
   <simpara>
    <filename>php://stdin</filename> es de solo lectura, mientras que
    <filename>php://stdout</filename> y <filename>php://stderr</filename> son
    de solo escritura.
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.input">
   <title>php://input</title>
   <simpara>
    <filename>php://input</filename> es un flujo de solo lectura que permite
    leer datos sin tratar desde el cuerpo de la petición.
    <filename>php://input</filename> no está disponible en las peticiones POST con
    <literal>enctype="multipart/form-data"</literal> si la opción
    <link linkend="ini.enable-post-data-reading">enable_post_data_reading</link>
    está activada.
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.output">
   <title>php://output</title>
   <para>
    <filename>php://output</filename> es un flujo de solo escritura, que permite escribir
    en el mecanismo de buffer de salida de la misma manera que las funciones
    <function>print</function> y
    <function>echo</function>.
   </para>
  </refsect2>

  <refsect2 xml:id="wrappers.php.fd">
   <title>php://fd</title>
   <simpara>
    <filename>php://fd</filename> permite acceso directo al descriptor de fichero
    especificado. Por ejemplo, <filename>php://fd/3</filename> corresponde al
    descriptor de fichero número 3.
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.memory">
   <title>php://memory y php://temp</title>
   <simpara>
    <filename>php://memory</filename> y <filename>php://temp</filename>
    son flujos de lectura/escritura que permiten almacenar datos
    temporales en una envoltura de ficheros. Una diferencia entre
    estos dos flujos es que <filename>php://memory</filename> almacenará siempre
    sus datos en memoria, mientras que <filename>php://temp</filename> utilizará un
    fichero temporal una vez que la cantidad de datos almacenados haya superado
    un límite predefinido (por omisión, 2 Mo). La ubicación
    de este fichero temporal se determina de la misma manera que para
    la función <function>sys_get_temp_dir</function>.
   </simpara>
   <simpara>
    El límite de memoria de <filename>php://temp</filename> puede ser controlado
    añadiendo <literal>/maxmemory:NN</literal>, donde <literal>NN</literal> es
    la cantidad máxima de datos a conservar en memoria antes de utilizar
    un fichero temporal, en bytes.
   </simpara>
   <caution>
    <simpara>
     Algunas extensiones PHP pueden requerir un flujo IO estándar,
     y pueden intentar convertir un flujo dado a un flujo IO estándar.
     Esta conversión puede fallar para los flujos de memoria, ya que la función C
     <function>fopencookie</function> debe estar disponible.
     Esta función C <emphasis>no está</emphasis> disponible en Windows.
    </simpara>
   </caution>
  </refsect2>

  <refsect2 xml:id="wrappers.php.filter">
   <title>php://filter</title>
   <simpara>
    <filename>php://filter</filename> es una especie de envoltura prevista
    para permitir la aplicación de <link linkend="filters">filtros</link>
    sobre un flujo en el momento de su apertura. Esto es muy práctico con
    funciones sobre ficheros todas-en-una como las funciones
    <function>readfile</function>, <function>file</function> y
    <function>file_get_contents</function>, donde no existe otro mecanismo
    que permita aplicar un filtro al flujo antes de que el contenido sea leído.
   </simpara>
   <para>
    La meta de <filename>php://filter</filename> toma los parámetros siguientes
    bajo la forma de componentes de su ruta. Varios filtros encadenados
    pueden ser especificados en una sola ruta. Consúltese los ejemplos
    para un uso correcto de estos parámetros.
   </para>
   <para>
    <table>
     <title>Parámetros de php://filter</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Nombre</entry>
        <entry>Descripción</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>
         <literal>resource=&lt;flujo a filtrar&gt;</literal>
        </entry>
        <entry>
         Este parámetro es requerido. Especifica el flujo que se desea
         filtrar.
        </entry>
       </row>
       <row>
        <entry>
         <literal>read=&lt;lista de filtros a aplicar a la lectura&gt;</literal>
        </entry>
        <entry>
         Este parámetro es opcional. Uno o más nombres de filtros
         pueden ser proporcionados aquí, separados por un carácter pipe (<literal>|</literal>).
        </entry>
       </row>
       <row>
        <entry>
         <literal>write=&lt;lista de filtros a aplicar a la escritura&gt;</literal>
        </entry>
        <entry>
         Este parámetro es opcional. Uno o más nombres de filtros
         pueden ser proporcionados aquí, separados por un carácter pipe (<literal>|</literal>).
        </entry>
       </row>
       <row>
        <entry>
         <literal>&lt;lista de filtros a aplicar tanto a la lectura como a la escritura&gt;</literal>
        </entry>
        <entry>
         Todos los filtros proporcionados sin ser prefijados por <literal>read=</literal>
         o <literal>write=</literal> serán aplicados tanto a la
         lectura como a la escritura.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
  </refsect2>
 </refsect1>

 <refsect1 role="options"><!-- {{{ -->
  &reftitle.options;
  <para>
   <table>
    <title>
     Resumen de la envoltura (para <literal>php://filter</literal>, consúltese
     el resumen de la envoltura a filtrar)
    </title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Atributo</entry>
       <entry>Soportado</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Restringido por <link linkend="ini.allow-url-fopen">allow_url_fopen</link></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Restringido por <link linkend="ini.allow-url-include">allow_url_include</link></entry>
       <entry>
        <literal>php://input</literal>,
        <literal>php://stdin</literal>,
        <literal>php://memory</literal> y
        <literal>php://temp</literal> únicamente.
       </entry>
      </row>
      <row>
       <entry>Permite la lectura</entry>
       <entry>
        <literal>php://stdin</literal>,
        <literal>php://input</literal>,
        <literal>php://fd</literal>,
        <literal>php://memory</literal> y
        <literal>php://temp</literal> únicamente.
       </entry>
      </row>
      <row>
       <entry>Permite la escritura</entry>
       <entry>
        <literal>php://stdout</literal>,
        <literal>php://stderr</literal>,
        <literal>php://output</literal>,
        <literal>php://fd</literal>,
        <literal>php://memory</literal> y
        <literal>php://temp</literal> únicamente.
       </entry>
      </row>
      <row>
       <entry>Permite la adición</entry>
       <entry>
        <literal>php://stdout</literal>,
        <literal>php://stderr</literal>,
        <literal>php://output</literal>,
        <literal>php://fd</literal>,
        <literal>php://memory</literal> y
        <literal>php://temp</literal> únicamente. (Equivalente a la escritura)
       </entry>
      </row>
      <row>
       <entry>Permite tanto la lectura como la escritura</entry>
       <entry>
        <literal>php://fd</literal>,
        <literal>php://memory</literal> y
        <literal>php://temp</literal> únicamente.
       </entry>
      </row>
      <row>
       <entry>Soporte de la función <function>stat</function></entry>
       <entry>
        No. Sin embargo, <literal>php://memory</literal> y
        <literal>php://temp</literal> soportan <function>fstat</function>.
       </entry>
      </row>
      <row>
       <entry>Soporte de la función <function>unlink</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Soporte de la función <function>rename</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Soporte de la función <function>mkdir</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Soporte de la función <function>rmdir</function></entry>
       <entry>No</entry>
      </row>
      <row>
       <entry>Soporte de la función <function>stream_select</function></entry>
       <entry>
        <literal>php://stdin</literal>,
        <literal>php://stdout</literal>,
        <literal>php://stderr</literal>,
        <literal>php://fd</literal> y
        <literal>php://temp</literal> únicamente.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1> <!-- }}} -->

 <refsect1 role="examples"><!-- {{{ -->
  &reftitle.examples;
  <example><!-- {{{ -->
   <title>php://temp/maxmemory</title>
   <para>
    Este parámetro opcional permite configurar el límite
    de memoria antes de que <filename>php://temp</filename> comience a utilizar
    un fichero temporal.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
// Define el límite a 5 Mo.
$fiveMBs = 5 * 1024 * 1024;
$fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

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

// Lee lo que acabamos de escribir.
rewind($fp);
echo stream_get_contents($fp);
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/resource=&lt;flujo a filtrar&gt;</title>
   <para>
    Este parámetro debe ser colocado al final de la especificación
    de <filename>php://filter</filename> y debe apuntar al flujo
    que se desea filtrar.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* Esto es equivalente a
  readfile("http://www.example.com");
  ya que no se especifica ningún filtro */

readfile("php://filter/resource=http://www.example.com");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/read=&lt;lista de filtros a aplicar a la lectura&gt;</title>
   <para>
    Este parámetro toma uno o más nombres de filtros separados por
    un carácter pipe <literal>|</literal>.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* Esto mostrará el contenido de
  www.example.com completamente en mayúsculas */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");

/* Esto hará lo mismo que el anterior,
  pero codificará además el resultado en ROT13 */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/write=&lt;lista de filtros a aplicar a la escritura&gt;</title>
   <para>
    Este parámetro toma uno o más nombres de filtros separados por
    un carácter pipe <literal>|</literal>.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* Esto filtrará la cadena "Hello World"
  a través del filtro rot13, y luego escribirá el resultado
  en el fichero example.txt del directorio actual */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example>
   <title>php://memory y php://temp no son reutilizables</title>
   <para>
    <filename>php://memory</filename> y <filename>php://temp</filename>
    no son reutilizables, es decir, después de que los flujos hayan sido cerrados no hay manera de referenciarlos nuevamente.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
file_put_contents('php://memory', 'PHP');
echo file_get_contents('php://memory'); // no muestra nada
]]>
   </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
-->