archived-doc-pt-br/reference/session/upload-progress.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: leonardolara Status: ready --><!-- CREDITS: marcosmarcolin -->

<chapter xml:id="session.upload-progress" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Progresso de Upload em Sessão</title>

 <para>
  Quando a configuração INI
  <link linkend="ini.session.upload-progress.enabled">session.upload_progress.enabled</link>
  estiver habilitada, o PHP será capaz de rastrear o progresso do upload de
  arquivos individuais que estiverem sendo feito upload.
  Esta informação não é muito útil para a requisição atual,
  mas durante o upload do arquivo uma aplicação pode enviar uma requisição POST
  para um endpoint separado (via <acronym>XHR</acronym> por exemplo) para checar o
  status.
 </para>
 <para>
  O progresso do upload estará disponível na variável super global <varname>$_SESSION</varname>
  quando um upload estiver em progresso e quando a requisição POST tiver uma variável com
  o mesmo nome que a configuração INI
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>
  estiver configurada.
  Quando o PHP detectar requisições como essa, ele preencherá um array em
  <varname>$_SESSION</varname>, onde o índice é um valor resultante da concatenação de
  <link linkend="ini.session.upload-progress.prefix">session.upload_progress.prefix</link>
  e
  <link linkend="ini.session.upload-progress.name">session.upload_progress.name</link>
  (configurações INI).
  O índice normalmente é obtido lendo essas configurações INI, ou seja
  <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>
  Também é possível <emphasis>cancelar</emphasis> o upload do arquivo em
  andamento ao definir o índice <literal>$_SESSION[$key]["cancel_upload"]</literal> para
  &true;.
  Quando houver upload de múltiplos arquivos em uma mesma requisição, isso vai cancelar apenas o
  upload dos arquivos que ainda estiverem em andamento e pendentes, mas não
  removerá uploads já concluídos com sucesso.
  Quando um upload é cancelado dessa forma, o índice <literal>error</literal> no array
  <varname>$_FILES</varname> será alterado para
  <constant>UPLOAD_ERR_EXTENSION</constant>.
 </para>
 <para>
  As configurações INI
  <link linkend="ini.session.upload-progress.freq">session.upload_progress.freq</link>
  e
  <link linkend="ini.session.upload-progress.min-freq">session.upload_progress.min_freq</link>
  controlam a frequência com que a informação do progresso do upload deve ser
  recalculado.
  Com um valor razoável para estas duas configurações, a sobrecarga
  desse recurso é quase inexistente.
 </para>
 <para>
  <example>
   <title>Exemplo de informação</title>
   <para>
    Exemplo de estrutura do array de progresso de upload.
   </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>
    Os dados armazenados na sessão serão parecidos com isto:
   </para>
   <programlisting role="php" xml:id="session.upload-progress.example-array">
<![CDATA[
<?php
$_SESSION["upload_progress_123"] = array(
 "start_time" => 1234567890,   // A hora da requisição
 "content_length" => 57343257, // tamanho do conteúdo de POST
 "bytes_processed" => 453489,  // Quantidade de bytes recebidos e processados
 "done" => false,              // true quando o manipulador do POST finalizar, com sucesso ou não
 "files" => array(
  0 => array(
   "field_name" => "file1",       // Nome do campo <input/>
   // Os próximos 3 elementos se assemelham aos de $_FILES
   "name" => "foo.avi",
   "tmp_name" => "/tmp/phpxxxxxx",
   "error" => 0,
   "done" => true,                // True quando o manipulador do POST terminar de manipular este arquivo
   "start_time" => 1234567890,    // Quando este arquivo começou a ser processado
   "bytes_processed" => 57343250, // Quantidade de bytes recebidos e processados para este arquivo
  ),
  // Um outro arquivo, em que o upload ainda não acabou, na mesma requisição
  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>
   O buffer de requisições do servidor web deve estar desabilitado para que isso funcione
   corretamente ou o PHP pode enxergar o upload apenas quando ele já estiver completado. É de conhecimento que servidores
   como Nginx criam buffer para requisições maiores.
  </para>
 </warning>
 <caution>
  <para>
   A informação do progresso do upload é escrita na sessão antes da execução de
   quaisquer scripts. Portanto, alterar o nome da sessão através da função <function>ini_set</function>
   ou <function>session_name</function> resultará em uma sessão sem as informações de
   progresso do upload.
  </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
-->