archived-doc-pt-br/reference/session/functions/session-set-save-handler.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: fernandowobeto Status: ready --><!-- CREDITS: surfmax,fernandoc,fernandowobeto -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>session_set_save_handler</refname>
  <refpurpose>Define funções de armazenamento de sessão à nível de usuário</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>callable</type><parameter>open</parameter></methodparam>
   <methodparam><type>callable</type><parameter>close</parameter></methodparam>
   <methodparam><type>callable</type><parameter>read</parameter></methodparam>
   <methodparam><type>callable</type><parameter>write</parameter></methodparam>
   <methodparam><type>callable</type><parameter>destroy</parameter></methodparam>
   <methodparam><type>callable</type><parameter>gc</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>create_sid</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>validate_sid</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>update_timestamp</parameter></methodparam>
  </methodsynopsis>
  <para>
   É possível registrar o seguinte protótipo:
  </para>
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>object</type><parameter>sessionhandler</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>register_shutdown</parameter><initializer>&true;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>session_set_save_handler</function> define, a nível de usuário,
   as funções de armazenamento de sessão que serão usadas para guardar e
   buscar dados associados à uma sessão.  Ela é mais útil
   quando um método de armazenamento diferente do método disponibilizado pelas sessões do PHP
   é preferido, por exemplo armazenar os dados de sessão em um banco de dados.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   Essa função tem dois protótipos.
   <variablelist>
    <varlistentry>
     <term><parameter>sessionhandler</parameter></term>
     <listitem>
      <para>
       Uma instância de uma classe implementando
       <interfacename>SessionHandlerInterface</interfacename>, e opcionalmente
       <interfacename>SessionIdInterface</interfacename> e/ou
       <interfacename>SessionUpdateTimestampHandlerInterface</interfacename>, como
       <classname>SessionHandler</classname>, para registrá-la como manipulador
       de sessão.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>register_shutdown</parameter></term>
     <listitem>
      <para>
       Registra <function>session_write_close</function> como uma função
       <function>register_shutdown_function</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

   ou

   <variablelist>
    <varlistentry>
     <term><parameter>open</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>open</replaceable></methodname>
        <methodparam><type>string</type><parameter>savePath</parameter></methodparam>
        <methodparam><type>string</type><parameter>sessionName</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       O callback open funciona igual um construtor em classes e é
       executado quando a sessão está sendo aberta.  É a primeira função de
       callback executada quando a sessão é iniciada automaticamente ou
       manualmente com <function>session_start</function>.
       O valor de retorno é &true; para sucesso, &false; para falha.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>close</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>close</replaceable></methodname>
        <void/>
       </methodsynopsis>
      </para>
      <para>
       O callback close funciona igual um destrutor em classes e é
       executado depois que o callback write da sessão for chamado. Ele também é invocado quando a função
       <function>session_write_close</function> é chamada.
       O valor de retorno é &true; para sucesso, &false; para falha.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>string</type><methodname><replaceable>read</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       O callback <parameter>read</parameter> sempre deve retornar uma sessão codificada (serializada) no formato
       string ou uma string vazia se não há dados para leitura.
      </para>
      <para>
       Esse callback é chamado internamente pelo PHP quando a sessão inicia ou
       quando a função <function>session_start</function> é chamada.  Antes que esse callback seja invocado,
       o PHP invocará o callback <parameter>open</parameter>.
      </para>
      <para>
       O valor que esse callback retorna deve estar exatamente no mesmo formato de serialização que originalmente foi
       passado para armazenamento ao callback <parameter>write</parameter>.  O valor retornado será
       desserializado automaticamente pelo PHP e usado para preencher a super global <varname>$_SESSION</varname>.
       Mesmo que os dados pareçam similares ao de <function>serialize</function>, note que é um formato diferente,
       especificado na configuração INI <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>write</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
        <methodparam><type>string</type><parameter>data</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       O callback <parameter>write</parameter> é chamado quando a sessão precisa ser salva e fechada. Esse
       callback recebe o ID da sessão atual e uma versão serializada da super global <varname>$_SESSION</varname>. O método de
       serialização usado internamente pelo PHP é definido pela configuração INI <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
      </para>
      <para>
       Os dados de sessão serializados passado para esse callback devem ser armazenados junto com o ID de sessão passado. Ao buscar
       esses dados, o callback <parameter>read</parameter> deve retornar exatamente o mesmo valor que foi passado originalmente para
       o callback <parameter>write</parameter>.
      </para>
      <para>
       Esse callback é invocado quando o PHP é encerrado ou explicitamente quando a função <function>session_write_close</function>
       é chamada.  Note que depois de executar esta função, o PHP executará internamente o callback <parameter>close</parameter>.
       <note>
        <para>
         O manipulador "write" não é executado enquanto o fluxo de saída não for
         encerrado.  Portanto, saídas de comandos de debug no manipulador "write"
         nunca serão vistas pelo browser.  Se a saída de debug é
         necessária, é recomendado que ela seja escrita
         em arquivo.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>destroy</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>destroy</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Esse callback é executado quando uma sessão é destruída com <function>session_destroy</function> ou com
       <function>session_regenerate_id</function> com o parâmetro de destruição definido como &true;.
       O valor de retorno deve ser &true; para sucesso, &false; para falha.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>gc</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>gc</replaceable></methodname>
        <methodparam><type>int</type><parameter>lifetime</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       O callback de limpeza (gc) é invocado pelo PHP, internamente e periodicamente, para
       apagar dados de sessão antiga.  A frequência é controlada por
       <link linkend="ini.session.gc-probability">session.gc_probability</link> e <link linkend="ini.session.gc-divisor">session.gc_divisor</link>.
       O valor do parâmetro que é passado para esse callback pode ser definido em <link linkend="ini.session.gc-maxlifetime">session.gc_maxlifetime</link>.
       O valor de retorno deve ser &true; para sucesso, &false; para falha.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>create_sid</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>string</type><methodname><replaceable>create_sid</replaceable></methodname>
        <void/>
       </methodsynopsis>
      </para>
      <para>
       Esse callback é executado quando um novo ID de sessão é necessário. Nenhum
       parâmetro é necessário e o valor de retorno deve ser uma string que
       seja um ID de sessão válido para seu manipulador.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>validate_sid</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>validate_sid</replaceable></methodname>
        <methodparam><type>string</type><parameter>key</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Este callback é executado quando uma sessão é iniciada, um ID de sessão é fornecido
       e <link linkend="ini.session.use-strict-mode">session.use_strict_mode</link> é habilitado.
       A <parameter>key</parameter> é o ID da sessão para validar.
       Um ID de sessão é válido se já existir uma sessão com esse ID.
       O valor retornado deve ser &true; em caso de sucesso, &false; em caso de falha.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>update_timestamp</parameter></term>
     <listitem>
      <para>
       Um callable com a seguinte assinatura:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>update_timestamp</replaceable></methodname>
        <methodparam><type>string</type><parameter>key</parameter></methodparam>
        <methodparam><type>string</type><parameter>val</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Este callback é executado quando uma sessão é atualizada.
       <parameter>key</parameter> é o ID da sessão, <parameter>val</parameter> são os dados da sessão.
       O valor retornado deve ser &true; em caso de sucesso, &false; em caso de falha.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Manipulador de sessão personalizado: veja o código completo na sinópse de <classname>SessionHandlerInterface</classname>.
    </title>
    <para>
     Aqui é demonstrado apenas a execução, o código completo pode ser
     visto na sinópse de <classname>SessionHandlerInterface</classname> no link acima.
    </para>
    <para>
     Note que é usado orientação à objetos com <function>session_set_save_handler</function> e
     a função de encerramento (register_shutdown) é registrada usando sua respectiva flag.  Isto geralmente é
     aconselhável ao registrar objetos como manipuladores de gravação de sessão.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
class MySessionHandler implements SessionHandlerInterface
{
    // implementa a interface aqui
}

$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();

// proceder para definir e recuperar os valores pela chave de $_SESSION
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    The <parameter>write</parameter> e
    <parameter>close</parameter> são executados depois da destruição de
    objetos e portanto não podem usar objetos ou lançar exceções.
    Não é possível capturar nem
    exibir o rastro (trace) de exceções e a execução simplesmente será interrompida de forma inesperada.
    Contudo, os destrutores do objeto podem usar sessões.
   </para>
   <para>
    É possível chamar <function>session_write_close</function> do
    destrutor para resolver esse problema de 'o ovo e a galinha' mas a forma mais confiável é
    registrar a função de finalização como descrito acima.
   </para>
  </warning>
  <warning>
   <para>
    O diretório de trabalho atual é alterado com algumas SAPIs (Server API) se a sessão for
    fechada na finalização do script. É possível fechar a sessão
    antecipadamente com <function>session_write_close</function>.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member>
     <link linkend="ini.session.save-handler">session.save_handler</link>
     (diretiva de configuração)
    </member>
    <member>
     <link linkend="ini.session.serialize-handler">session.serialize_handler</link>
     (diretiva de configuração)
    </member>
    <member>A <function>register_shutdown_function</function></member>
    <member>The <function>session_register_shutdown</function></member>
    <member>
     Visite <link xlink:href="&url.session-save-handler;">save_handler.inc</link>
     para ver uma implementação completamente procedural
    </member>
   </simplelist>
  </para>
 </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
-->