archived-doc-es/reference/session/upload-progress.xml

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

<chapter xml:id="session.upload-progress" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Progresión de una subida (upload) en sesión</title>

 <para>
  Cuando la opción de configuración
  <link linkend="ini.session.upload-progress.enabled">session.upload_progress.enabled</link>
  está activa, PHP será capaz de rastrear la progresión de un fichero en
  curso de subida (upload). Esta información no es particularmente útil
  para la petición de subida en sí, pero durante la subida,
  una aplicación puede enviar una petición POST separada (por ejemplo,
  mediante <acronym>XHR</acronym>) para verificar el estado de esta subida.
 </para>
 <para>
  La progresión de la subida estará disponible en la variable superglobal
  <varname>$_SESSION</varname> cuando la subida está en curso,
  y durante un envío en método POST de una variable con el mismo nombre que el
  definido en la opción de configuración INI
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>.
  Cuando PHP detecta una petición POST de este tipo, llenará un array en
  <varname>$_SESSION</varname>, donde el índice es un valor concatenado de las opciones
  de configuración
  <link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link>
  y
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>.
  La clave se recupera típicamente leyendo estas configuraciones INI, es decir:
  <informalexample>
   <programlisting role="php">
<![CDATA[
<?php
$key = ini_get("session.upload_progress.prefix") . $_POST[ini_get("session.upload_progress.name")];
var_dump($_SESSION[$key]);
?>
]]>
   </programlisting>
  </informalexample>
 </para>
 <para>
  Asimismo, es posible <emphasis>cancelar</emphasis> la subida actual
  definiendo la clave <literal>$_SESSION[$key]["cancel_upload"]</literal> al valor
  &true;. Durante la subida de varios ficheros en la misma
  petición, esta acción solo cancelará el fichero actualmente en curso de subida,
  así como aquellos en espera de subida, pero no cancelará las subidas
  terminadas con éxito. Cuando una subida es cancelada utilizando este método,
  la clave <literal>error</literal> del array <varname>$_FILES</varname> será definida a
  <constant>UPLOAD_ERR_EXTENSION</constant>.
 </para>
 <para>
  Las opciones de configuración INI
  <link linkend="ini.session.upload-progress.freq">session.upload_progress.freq</link>
  y
  <link linkend="ini.session.upload-progress.min-freq">session.upload_progress.min_freq</link>
  controlan la frecuencia de actualización de las informaciones de progresión de subida.
  Con una configuración razonable de estas 2 opciones, el sobrecoste en términos
  de carga es casi nulo.
 </para>
 <para>
  <example>
   <title>Ejemplo</title>
   <para>
    Ejemplo de estructura del array que contiene las informaciones de
    subida.
   </para>
   <programlisting role="html" xml:id="session.upload-progress.example-form">
<![CDATA[
<form action="upload.php" method="POST" enctype="multipart/form-data">
 <input type="hidden" name="<?php echo ini_get("session.upload_progress.name"); ?>" value="123" />
 <input type="file" name="file1" />
 <input type="file" name="file2" />
 <input type="submit" />
</form>
]]>
   </programlisting>
   <para>
    Los datos almacenados en sesión se asemejarán a:
   </para>
   <programlisting role="php" xml:id="session.upload-progress.example-array">
<![CDATA[
<?php
$_SESSION["upload_progress_123"] = array(
 "start_time" => 1234567890,   // La hora de la petición
 "content_length" => 57343257, // Longitud del contenido POST
 "bytes_processed" => 453489,  // Cantidad de bytes recibidos y procesados
 "done" => false,              // true cuando el manejador POST ha terminado, con éxito o no
 "files" => array(
  0 => array(
   "field_name" => "file1",       // Nombre del campo <input/>
   // Los 3 elementos siguientes son equivalentes a los en $_FILES
   "name" => "foo.avi",
   "tmp_name" => "/tmp/phpxxxxxx",
   "error" => 0,
   "done" => true,                // True cuando el manejador POST ha terminado de manejar este fichero
   "start_time" => 1234567890,    // La hora de inicio de petición
   "bytes_processed" => 57343250, // Cantidad de bytes recibidos y procesados para este fichero
  ),
  // Otro fichero, en curso de subida, en la misma petición
  1 => array(
   "field_name" => "file2",
   "name" => "bar.avi",
   "tmp_name" => NULL,
   "error" => 0,
   "done" => false,
   "start_time" => 1234567899,
   "bytes_processed" => 54554,
  ),
 )
);
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <para>
   El almacenamiento en búfer de la petición del servidor web debe estar desactivado
   para el buen funcionamiento de esta funcionalidad, de lo contrario PHP solo verá el fichero
   una vez que esté completamente subido. Los servidores como Nginx son conocidos por almacenar en búfer
   grandes peticiones.
  </para>
 </warning>
 <caution>
  <para>
   Las informaciones de progresión de la subida son escritas en sesión antes
   de que un script sea ejecutado. Por consecuencia, cambiar el nombre de sesión mediante
   <function>ini_set</function> o <function>session_name</function> dará una
   sesión sin las informaciones de progresión de la subida.
  </para>
 </caution>

</chapter>

<!-- 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
-->