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

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

<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>Configura las funciones de almacenamiento de sesiones</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>
   Es posible registrar el siguiente prototipo:
  </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> configura las funciones
   de almacenamiento de sesiones, y permite elegir funciones de usuario
   para guardar y leer todas las sesiones. Esta función es
   muy práctica cuando se necesita guardar los datos de sesión
   utilizando una técnica diferente al sistema de archivos proporcionado
   por defecto, por ejemplo, el almacenamiento en base de datos.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   Esta función tiene dos prototipos.
   <variablelist>
    <varlistentry>
     <term><parameter>sessionhandler</parameter></term>
     <listitem>
      <para>
       Una instancia de una clase que implementa una o más de las siguientes interfaces:
       <interfacename>SessionHandlerInterface</interfacename>, y opcionalmente
       <interfacename>SessionIdInterface</interfacename>, y/o
       <interfacename>SessionUpdateTimestampHandlerInterface</interfacename>,
       como la clase <classname>SessionHandler</classname>,
       para el registro como manejador de sesión.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>register_shutdown</parameter></term>
     <listitem>
      <para>
       Registra la función <function>session_write_close</function>
       como función <function>register_shutdown_function</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

   o

   <variablelist>
    <varlistentry>
     <term><parameter>open</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <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>
       La función de retorno <literal>open</literal> funciona como un constructor
       en una clase, y se ejecuta cuando la sesión se abre.
       Es la primera función de retorno ejecutada cuando la sesión
       comienza automáticamente o manualmente con la función
       <function>session_start</function>. El valor devuelto
       es &true; en caso de éxito o &false; si ocurre un error.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>close</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>close</replaceable></methodname>
        <void/>
       </methodsynopsis>
      </para>
      <para>
       La función de retorno <literal>close</literal> funciona como un
       destructor en una clase, y se ejecuta una vez que la función
       de retorno write de la sesión ha terminado de ejecutarse. También
       es llamada cuando la función <function>session_write_close</function> es llamada.
       El valor devuelto es &true; en caso de éxito, o &false; si ocurre un error.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <methodsynopsis>
        <type>string</type><methodname><replaceable>read</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       La función de retorno <parameter>read</parameter> debe siempre devolver
       un string serializado que contenga los datos de sesión codificados
       o un string vacío si no hay datos que leer.
      </para>
      <para>
       Esta función de retorno es llamada internamente por PHP cuando la sesión
       comienza o cuando la función <function>session_start</function> es llamada.
       Antes de que esta función de retorno sea invocada, PHP invocará
       la función de retorno <parameter>open</parameter>.
      </para>
      <para>
       El valor devuelto por esta función de retorno debe ser exactamente del mismo
       formato de serialización que el pasado para el almacenamiento a la función
       de retorno <parameter>write</parameter>. El valor devuelto será deserializado
       automáticamente por PHP y utilizado para poblar la variable superglobal
       <varname>$_SESSION</varname>. Aunque los datos se asemejen fuertemente
       a los emitidos por la función <function>serialize</function>, note que es un
       formato diferente, que es especificado mediante la opción de configuración
       <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <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>
       La función de retorno <parameter>write</parameter> es llamada cuando la sesión
       debe ser guardada y cerrada. Esta función de retorno recibe el identificador de
       la sesión actual así como una versión serializada del contenido de la variable
       superglobal <varname>$_SESSION</varname>. El método de serialización utilizado internamente
       por PHP es especificado mediante la opción de configuración
       <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
      </para>
      <para>
       Los datos de sesión serializados pasados a esta función de retorno deben ser
       almacenados utilizando el identificador de sesión proporcionado. Al recuperar
       estos datos, la función de retorno <parameter>read</parameter> debe devolver
       el valor exacto, originalmente pasado a la función de retorno <parameter>write</parameter>.
      </para>
      <para>
       Esta función de retorno es invocada cuando PHP se detiene o explícitamente
       cuando la función <function>session_write_close</function> es llamada.
       Note que después de la ejecución de esta función, PHP ejecutará internamente
       la función de retorno <parameter>close</parameter>.
       <note>
        <para>
         El manejador de escritura no se ejecuta hasta que el flujo de salida
         no haya sido cerrado. Por lo tanto, la salida de las peticiones de depuración
         del manejador "write" nunca será mostrada en el navegador.
         Si la salida de depuración es necesaria, se sugiere que sea dirigida a un archivo.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>destroy</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>destroy</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Esta función de retorno es ejecutada cuando una sesión es destruida
       con la función <function>session_destroy</function> o con
       <function>session_regenerate_id</function> con el parámetro de destrucción definido
       a &true;. El valor devuelto debe ser &true; en caso de éxito, o &false; si ocurre un error.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>gc</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>gc</replaceable></methodname>
        <methodparam><type>int</type><parameter>lifetime</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       La función de retorno del recolector de basura es invocada internamente por PHP
       periódicamente para purgar los datos de sesión antiguos. La frecuencia
       es controlada por las opciones de configuración
       <link linkend="ini.session.gc-probability">session.gc_probability</link> y
       <link linkend="ini.session.gc-divisor">session.gc_divisor</link>.
       El valor de la duración de vida pasado a esta función de retorno puede ser
       definido mediante la opción de configuración <link linkend="ini.session.gc-maxlifetime">session.gc_maxlifetime</link>.
       El valor devuelto debe ser &true; en caso de éxito, o &false; si ocurre un error.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>create_sid</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <methodsynopsis>
        <type>string</type><methodname><replaceable>create_sid</replaceable></methodname>
        <void/>
       </methodsynopsis>
      </para>
      <para>
       Esta función de retorno es ejecutada cuando se necesita un nuevo ID de sesión.
       No se proporcionan parámetros, y el valor devuelto debe ser un string que es un ID de sesión válido para su manejador.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>validate_sid</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>validate_sid</replaceable></methodname>
        <methodparam><type>string</type><parameter>key</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Esta función de retorno es ejecutada cuando una sesión va a comenzar, un ID
       de sesión es proporcionado y
       <link linkend="ini.session.use-strict-mode">session.use_strict_mode</link>
       está activado.
       <parameter>key</parameter> es el ID de sesión a validar.
       Un ID de sesión es válido, si una sesión con este ID ya existe.
       El valor de retorno debe ser &true; en caso de éxito, &false; en caso de fallo.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>update_timestamp</parameter></term>
     <listitem>
      <para>
       Una función de retorno con la siguiente firma:
       <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>
       Esta función de retorno es ejecutada cuando una sesión es actualizada.
       <parameter>key</parameter> es el ID de sesión, <parameter>val</parameter>
       son los datos de sesión.
       El valor de retorno debe ser &true; en caso de éxito, &false; en caso de fallo.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

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

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Manejador de sesión personalizado: ver el código completo
     en la documentación sobre la interfaz <classname>SessionHandlerInterface</classname>.
    </title>
    <para>
     Solo mostramos la invocación aquí, el ejemplo completo puede verse en
     la documentación de la interfaz
     <classname>SessionHandlerInterface</classname>.
    </para>
    <para>
     Note que aquí utilizamos el prototipo orientado a objetos con
     <function>session_set_save_handler</function> y registramos la función de cierre
     utilizando el flag en el parámetro de la función. Esto es generalmente
     preferible al registrar objetos como manejadores de guardado de sesión.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
class MySessionHandler implements SessionHandlerInterface
{
    // implementación de la interfaz aquí
}

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

// proceso para definir y recuperar los valores por sus claves desde $_SESSION
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    Los manejadores de escritura <parameter>write</parameter> y cierre
    <parameter>close</parameter> son llamados después de la destrucción de los objetos,
    y por lo tanto, no pueden utilizar los objetos ni lanzar excepciones.
    Las excepciones no pueden ser atrapadas ni mostradas,
    y la ejecución solo se detendrá de manera inesperada.
   </para>
   <para>
    Es posible llamar a <function>session_write_close</function> desde
    el destructor para resolver este problema pero la forma más elegante
    es registrar la función de cierre tal como se describe arriba.
   </para>
  </warning>
  <warning>
   <para>
    El directorio de trabajo actual cambia según las SAPIs si la sesión
    es cerrada al final del script. Es posible cerrar la sesión más tarde,
    gracias a la función <function>session_write_close</function>.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member>
     La directiva de configuración <link linkend="ini.session.save-handler">session.save_handler</link>
    </member>
    <member>
     La directiva de configuración
     <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
    </member>
    <member><function>register_shutdown_function</function></member>
    <member><function>session_register_shutdown</function></member>
    <member>
     Ver <link xlink:href="&url.session-save-handler;">save_handler.inc</link>
     para una implementación procedimental completa
    </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
-->