mirror of
https://github.com/php/doc-es.git
synced 2026-03-25 07:52:21 +01:00
48db252cf2
git-svn-id: https://svn.php.net/repository/phpdoc/es/trunk@334831 c90b9560-bf6c-de11-be94-00142212c4b1
420 lines
16 KiB
XML
420 lines
16 KiB
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
|
|
-->
|