archived-doc-pt-br/reference/session/examples.xml

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

<appendix xml:id="session.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.examples;
 <section xml:id="session.examples.basic">
  <title>Uso básico</title>
   <para>
    Sessões são uma forma simples de armazenar dados para usuários individuais usando um ID de sessão único.
    Sessões podem ser usadas para persistir informações entre requisições de páginas.  IDs de sessão normalmente são
    enviados ao navegador através de cookies de sessão e o ID é usado para recuperar dados da sessão existente.
    A ausência de um ID ou cookie de sessão permite que o PHP saiba que deve criar uma nova sessão e gerar um novo
    ID de sessão.
   </para>
   <para>
    Sessões seguem um fluxo simples.  Quando uma sessão é iniciada, o PHP recupera uma
    sessão existente usando o ID informado (normalmente de um cookie de sessão) ou se nenhum é informado
    então será criada uma nova sessão.  O PHP preencherá a super global <varname>$_SESSION</varname>
    com todos os dados de sessão depois que a sessão iniciar.  Quando o PHP finalizar, automaticamente ele
    pegará o conteúdo da super global <varname>$_SESSION</varname>, então vai serializá-lo e enviá-lo
    para armazenamento usando o manipulador de gravação da sessão.
   </para>
   <para>
    Por padrão, o PHP usa o manipulador de gravação interno <parameter>files</parameter> que
    é configurado por <link linkend="ini.session.save-handler">session.save_handler</link>.
    Isto salva os dados da sessão no servidor no local configurado pela
    diretiva de configuração <link linkend="ini.session.save-path">session.save_path</link>.
   </para>
   <para>
    Sessões podem ser iniciadas manualmente usando a função <function>session_start</function>.
    Se a diretiva <link linkend="ini.session.auto-start">session.auto_start</link> estiver configurada
    como <parameter>1</parameter>, a sessão será iniciada automaticamente no início da requisição.
   </para>
   <para>
    Sessões normalmente se encerram automaticamente quando o PHP termina de executar um script, mas podem ser
    encerradas manualmente usando a função <function>session_write_close</function>.
   </para>
  <para>
   <example>
    <title>
     Registrando uma variável com <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
if (!isset($_SESSION['count'])) {
  $_SESSION['count'] = 0;
} else {
  $_SESSION['count']++;
}
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>
     Desregistrando uma variável com <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
<![CDATA[
<?php
session_start();
unset($_SESSION['count']);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <caution>
    <para>
     NÃO desregistre toda a <varname>$_SESSION</varname> com
     <literal>unset($_SESSION)</literal> já que isso desativará o
     registro de variáveis de sessões da
     super global <varname>$_SESSION</varname>.
    </para>
   </caution>
  </para>
  <warning>
   <para>
    Referências não podem ser usadas nas variáveis de sessão já que não existe uma maneira
    de restaurar uma referência para outra variável.
   </para>
  </warning>
  <note>
   <para>
    Sessões baseadas em arquivos (padrão no PHP) adicionam travas no arquivo de sessão assim que
    a sessão é iniciada via <function>session_start</function> ou simplesmente via
    <link linkend="ini.session.auto-start">session.auto_start</link>. Assim que
    adicionada a trava, nenhum outro script pode acessar o mesmo arquivo de sessão até que ela
    seja finalizada pelo encerramento do primeiro script ou pela chamada de
    <function>session_write_close</function>.
   </para>
   <para>
    Isto é possivelmente um problema para web sites que utilizam fortemente o AJAX e
    que tem múltiplas solicitações concorrentes. A maneira mais fácil de lidar com isto é
    chamar <function>session_write_close</function> assim que as
    alterações necessárias na sessão forem feitas, de preferência no início do script.
    Como alternativa, um manipulador de sessão diferente que suporte concorrência
    poderia ser usado.
   </para>
  </note>
 </section>

 <section xml:id="session.idpassing">
  <title>Passando o ID de sessão</title>
  <para>
   Existem dois métodos para a propagação do id de sessão:
   <itemizedlist>
    <listitem>
     <simpara>
      Cookies
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      URL parameter
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   O módulo de sessão suporta ambos os métodos. Cookies são melhores, mas
   como nem sempre eles estão disponíveis, também é oferecido um método
   alternativo. O segundo método embute o id de sessão diretamente nas URLs.
  </para>
  <para>
   O PHP é capaz de transformar links de forma transparente. Se a opção
   de tempo de execução <literal>session.use_trans_sid</literal> estiver habilitada,
   URIs relativas serão alteradas automaticamente para conter o ID da sessão.
   <note>
    <para>
    O <link linkend="ini.arg-separator.output">arg_separator.output</link>,
    diretiva &php.ini;, permite configurar o separador de argumentos. Para completa
    conformidade com XHTML, especifique &amp;amp; aqui.
    </para>
   </note>
  </para>
  <para>
   Alternativamente, pode ser usada a constante <constant>SID</constant>, a qual é
   definida se uma sessão é iniciada.  Se o cliente não enviou um cookie de sessão
   apropriado, a constante terá o formato <literal>session_name=session_id</literal>.
   Se não, ela será uma string vazia. Dessa forma, ela pode ser colocada
   incondicionalmente em URLs.
  </para>
  <para>
   O exemplo a seguir demonstra como registrar uma variável e
   como criar um link corretamente para outra página usando o <constant>SID</constant>.
   <example>
    <title>Contando o número de acessos de um único usuário</title>
    <programlisting role="php">
<![CDATA[
<?php

session_start();

if (empty($_SESSION['count'])) {
   $_SESSION['count'] = 1;
} else {
   $_SESSION['count']++;
}
?>

<p>
Olá visitante, você acessou esta página <?php echo $_SESSION['count']; ?> vezes.
</p>

<p>
Para continuar, <a href="nextpage.php?<?php echo htmlspecialchars(SID); ?>">clique
aqui</a>.
</p>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   A função <function>htmlspecialchars</function> pode ser usada ao mostrar o <constant>SID</constant>
   com o intuito de prevenir ataques relacionados a XSS.
  </para>
  <para>
   Mostrar o <constant>SID</constant>, como mostrado acima, não é necessário se
   <link linkend="ini.session.use-trans-sid">
   --enable-trans-sid</link> foi usado para compilar o PHP.
  </para>
  <note>
   <para>
    Para URLs não-relativas, assume-se que elas apontam para sites externos e
    por isso não é adicionado o <constant>SID</constant>, já que seria um risco de segurança
    vazar o <constant>SID</constant> para um servidor diferente.
   </para>
  </note>
 </section>

 <section xml:id="session.customhandler">
  <title>Manipuladores de Sessão Personalizados</title>
  <para>
   Para implementar as sessões em banco de dados, ou qualquer outro método de armazenamento, é
   preciso usar <function>session_set_save_handler</function> para
   criar um conjunto de funções de armazenamento a nível de usuário. Um manipulador de sessão pode ser criado
   usando <classname>SessionHandlerInterface</classname> ou estender os manipuladores internos do PHP herdando
   de <classname>SessionHandler</classname>.
  </para>
  <para>
   Os callbacks especificados em <function>session_set_save_handler</function> são métodos
   executados pelo PHP durante o ciclo de vida de uma sessão: <parameter>open</parameter>, <parameter>read</parameter>,
   <parameter>write</parameter> e <parameter>close</parameter> e para as tarefas de manutenção:
   <parameter>destroy</parameter> para deletar uma sessão e <parameter>gc</parameter> para recolha periódica
   de lixo.
  </para>
  <para>
   Portanto, o PHP sempre requer manipuladores de gravação de sessão. O padrão normalmente é
   o manipulador de gravação interno de 'arquivos'. Um manipulador personalizado pode ser configurado usando
   <function>session_set_save_handler</function>. Manipuladores internos alternativos também são
   disponibilizados por extensões do PHP, como <parameter>sqlite</parameter>,
   <parameter>memcache</parameter> e <parameter>memcached</parameter> e podem ser definidos com
   <link linkend="ini.session.save-handler">session.save_handler</link>.
  </para>
  <para>
   Quando a sessão inicia, o PHP internamente executa o manipulador <parameter>open</parameter> seguido pelo
   callback <parameter>read</parameter> que deve retornar uma string codificada exatamente como foi originalmente
   passado para armazenamento. Após o <parameter>read</parameter> retornar a string codificada, o PHP vai
   decodificá-la e colocar o array resultante na super global <varname>$_SESSION</varname>.
  </para>
  <para>
   Quando o PHP é encerrado (ou quando <function>session_write_close</function> for chamada),
   o PHP internamente vai codificar a super global <varname>$_SESSION</varname> e passá-la
   junto com o ID de sessão para o callback <parameter>write</parameter>.
   Depois que o callback <parameter>write</parameter> finalizar, o PHP internamente invocará o
   callback <parameter>close</parameter>.
  </para>
  <para>
   Quando uma sessão é destruída, o PHP chamará o manipulador <parameter>destroy</parameter> com
   o ID de sessão.
  </para>
 <para>
   O PHP executará o callback <parameter>gc</parameter> de tempo em tempo para
   apagar quaisquer informações na sessão de acordo com o tempo de vida máximo (lifetime) definido para a sessão.
   Esta rotina deve apagar todas as informações do armazenamento persistente em que
   a diferença de tempo do último acesso até o momento atual seja maior que <parameter>$lifetime</parameter>.
 </para>
 </section>
</appendix>

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