session-set-save-handler.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: c38e57680de5e8149954272763f789add08db15a Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: andresdzphp -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler">
 <refnamediv>
  <refname>session_set_save_handler</refname>
  <refpurpose>Establece funciones de almacenamiento de sesiones a nivel de usuario</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>
  </methodsynopsis>
  <para>
   Desde PHP 5.4 es posible registrar el siguiente prototipo:
  </para>
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>SessionHandlerInterface</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> establece las funciones
   de almacenamiento de sesiones a nivel de usuario que se usan para almacenar y
   recuperar información asociada con una sesión. Es más útil
   cuando se prefiere un método de almacenamiento distinto de aquellos proporcionados
   por las sesiones de PHP. Esto es, almacenar la información de sesión en una base de datos local.
  </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 implemente
       <interfacename>SessionHandlerInterface</interfacename>, tal como
       <classname>SessionHandler</classname>, para registrarla como el gestor de
       sesión. Sólo desde PHP 5.4.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>register_shutdown</parameter></term>
     <listitem>
      <para>
       Registrar la función <function>session_write_close</function> como una
       función <function>register_shutdown_function</function>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   
   o
   
   <variablelist>
    <varlistentry>
     <term><parameter>open(string $savePath, string $sessionName)</parameter></term>
     <listitem>
      <para>
       La llamada de retorno open funciona como un constructor en las clases y es
       ejecutada cuando la sesión está siendo abierta. Es la primera función de llamada
       de retorno ejecutada cuando la sesión se inicia automáticamente o
       manualmente con <function>session_start</function>.
       El valor devuelto es &true; en caso de éxito, &false; en caso de error.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>close()</parameter></term>
     <listitem>
      <para>
       La llamada de retorno close funciona como un destructor en las clases y es
       ejecutada después de haber llamado a la llamada de retorno write de la sesión. También se invoca cuando
       se llama a <function>session_write_close</function>.
       El valor devuelto debería ser &true; en caso de éxito, &false; en caso de error.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>read(string $sessionId)</parameter></term>
     <listitem>
      <para>
       La llamada de retorno <parameter>read</parameter> debe devolver siempre una cadena de sesión
       (serializada), o una cadena vacía si no existe información que leer.
      </para>
      <para>
       Esta llamada de retorno es llamda internamente por PHP cuando se inicia la sesión o
       cuando se llama a <function>session_start</function>. Antes de invocar a esta llamada de sesión
       PHP invocará a la llamda de retorno <parameter>open</parameter>.
      </para>
      <para>
       El valor que devuelve esta llamada de retorno debe estar exactamente en el mismo formato de serialización que fue originalmente
       pasado para el almacenamiento de la llamada de retorno <parameter>write</parameter>. El valor devuelto será deserializado
       automáticamente por PHP y srá usado para rellenar la variable superglobal <varname>$_SESSION</varname>.
       Aunque la información parezca similar a <function>serialize</function>, observe que está en un formato diferente,
       el cual está especificado en la configuración ini <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write(string $sessionId, string $data)</parameter></term>
     <listitem>
      <para>
       La llamada de retorno <parameter>write</parameter> es llamada cuando la sesión necesita ser almacenada y cerrada. Esta
       llamada de retorno recibe el ID de sesión actual, una versión serializada de la variable superglobal <varname>$_SESSION</varname>. El método de
       serialización usado internamente por PHP está especificado en la configuración ini <link linkend="ini.session.serialize-handler">session.serialize_handler</link>.
      </para>
      <para>
       La información serializada de sesión pasada a esta llamada de retorno debería ser almacenada junto con el ID de sesión pasado. Al recuperar
       esta información, la llamada de retorno <parameter>read</parameter> debe devolver el valor exacto que fue pasado originalmente a
       la llamda de retorno <parameter>write</parameter>.
      </para>
      <para>
       Esta llamada de retorno es invocada cuando PHP se cierra o cuando se llamda explícitamente a
       <function>session_write_close</function>. Observe que después de ejecutar esta función PHP ejecutará internamente la llamada de retorno <parameter>close</parameter>.
       <note>
        <para>
         El gestor "write" no se ejecuta hasta después de que se cierre el flujo
         de salida. Así, la salida desde declaraciones de depuración en el gestor "write"
         nunca serán vistas en el navegador. Si es necesaria la salida de depuración,
         se sugiere que la salida de depuración sea escrita en un archivo
         en su lugar.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>destroy($sessionId)</parameter></term>
     <listitem>
      <para>
       Esta llamada de retorno es ejecutada cuando una sesión es destruida con <function>session_destroy</function> o con
       <function>session_regenerate_id</function> con el parámetro destroy establecido en &true;.
       El valor devuelto debería ser &true; en caso de éxito, &false; en caso de error.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>gc($lifetime)</parameter></term>
     <listitem>
      <para>
       La llamada de retorno del recolector de basura (Garbage Collector) es invocada internamente por PHP de manera periódica para
       destruir información antigua de sesiones. La frecuencia es controlada por
       <link linkend="ini.session.gc-probability">session.gc_probability</link> y <link linkend="ini.session.gc-divisor">session.gc_divisor</link>.
       El valor del tiempo de vida (lifetime) que es pasado a esta llamada de retorno puede establecerse en <link linkend="ini.session.gc-maxlifetime">session.gc_maxlifetime</link>.
       El valor devuelto debería ser &true; en caso de éxito, &false; en caso de error.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>create_sid()</parameter></term>
     <listitem>
      <para>
       Esta retrollamada se ejecuta cuando se requiere un nuevo ID de sesión. No
       se proporcionan parámetros, y el valor devuelto debería ser un string que
       sea un ID de sesión válido para el gestor utilizado.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Gestor de seseiones personalizado: véase el código completo en la sinopsis de <classname>SessionHandlerInterface</classname>.
    </title>
    <para>
     El siguiente código es para la versión 5.4.0 y superiror de PHP. Aquí se muestra la invocación, el código completo puede
     verse en la sinopsis de <classname>SessionHandlerInterface</classname> vinculada más arriba.
    </para>
    <para>
     Observe que usamos el prototipo de POO con <function>session_set_save_handler</function> y
     registramos la función de cierre usando la bandera de parámetro de la función. Esto se recomienda
     generalmente al registrar objetos como gestores de almacenamiento de sesiones.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
class MySessionHandler implements SessionHandlerInterface
{
    // implementar las interfaces aquí
}

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

// proceder a estblecer y recuperar valores mediante clave desde $_SESSION
]]>
    </programlisting>
   </example>
   <example>
    <title>Gestor de almacenamiento de sesiones personalizado usando objetos</title>
    <para>
     El siguiente código es para versiones de PHP inferiores a 5.4.0.
    </para>
    <para>
     El siguiente ejemplo proporciona un almacenamiento de sesiones basado en fichero similar al
     gestor de almacenamiento de sesiones de PHP predeterminado <parameter>files</parameter>. Este
     ejemplo podría extenderse fácilmente para cubrir el almacenamiento de bases de datos usando su
     motor de bases de datos favorito soportado por PHP.
    </para>
    <para>
     Observe que registramos de forma adicional la función de cierre <function>session_write_close</function>
     usando <function>register_shutdown_function</function> bajo PHP inferior a 5.4.0.
     Esto se recomienda generalmente al registrar objetos como gestores de almacenamiento de sesiones bajo PHP inferior
     a 5.4.0.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
class FileSessionHandler
{
    private $savePath;

    function open($savePath, $sessionName)
    {
        $this->savePath = $savePath;
        if (!is_dir($this->savePath)) {
            mkdir($this->savePath, 0777);
        }

        return true;
    }

    function close()
    {
        return true;
    }

    function read($id)
    {
        return (string)@file_get_contents("$this->savePath/sess_$id");
    }

    function write($id, $data)
    {
        return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
    }

    function destroy($id)
    {
        $file = "$this->savePath/sess_$id";
        if (file_exists($file)) {
            unlink($file);
        }

        return true;
    }

    function gc($maxlifetime)
    {
        foreach (glob("$this->savePath/sess_*") as $file) {
            if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
                unlink($file);
            }
        }

        return true;
    }
}

$handler = new FileSessionHandler();
session_set_save_handler(
    array($handler, 'open'),
    array($handler, 'close'),
    array($handler, 'read'),
    array($handler, 'write'),
    array($handler, 'destroy'),
    array($handler, 'gc')
    );

// lo siguiente previene de efectos inesperados al usar objetos como gestores de almacenamiento
register_shutdown_function('session_write_close');

session_start();
// proceder para establecer y recuperar valores por clave desde $_SESSION
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    Cuando se usan objetos como gestores de almacenamiento de sesionea es importante registrar la
    función de cierre con PHP para evitar efectos secundarios inesperados ya que
    PHP internamente destruye objetos en el cierre y puede prevenir que
    <parameter>write</parameter> y <parameter>close</parameter> sean llamados.
    Normalmente se debería registrar <parameter>'session_write_close'</parameter> usando la
    función <function>register_shutdown_function</function>.
   </para>
   <para>
    A partir de PHP 5.4.0 se puede usar <function>session_register_shutdown</function> o
    simplemente la bandera 'register shutdown' al invocar
    <function>session_set_save_handler</function> usando el método de POO the OOP y pasando una
    instancia que implemente <classname>SessionHandlerInterface</classname>.
   </para>
  </warning>
  <warning>
   <para>
    A partir de PHP 5.0.5 los gestores <parameter>write</parameter> y
    <parameter>close</parameter> son llamados después de la destrucción
    del objeto y por lo tanto no pueden usar objetos o lanzar excepciones.
    Las excepciones no pueden ser capturadas ya que no serán capturadas ni
    cualquier rastro de excepción será mostrado y la ejecución se interrumpirá de improviso.
    Sin embargo, los destructores de objetos pueden usar sesiones.
   </para>
   <para>
    Es posible llamar a <function>session_write_close</function> desde el
    destructor para solucionar este problema de "quién fue antes, si el huevo o la gallina" pero la forma más fiable es
    registrar la función de ceirre como está descrito más arraba.
   </para>
  </warning>
  <warning>
   <para>
    El directorio de trabajo actual es cambiado en algunas SAPI si la sesión
    se cierra al finalizar el script. Es posible cerrar la sesión antes
    con <function>session_write_close</function>.
   </para>
  </warning>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>5.5.1</entry>
      <entry>
       Se añadió el parámetro opcional <parameter>create_sid</parameter>.
      </entry>
     </row>
     <row>
      <entry>5.4.0</entry>
      <entry>
       Se añadió <interfacename>SessionHandlerInterface</interfacename> para la implementación de gestores de sesión y
       <classname>SessionHandler</classname> para exponer gestores de sesión internos de PHP.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </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>La función <function>register_shutdown_function</function></member>
    <member>La función <function>session_register_shutdown</function> para PHP 5.4.0+</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
-->