archived-doc-es/reference/session/examples.xml

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

<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>
   Las sesiones son una forma sencilla de almacenar datos individuales para cada
   usuario mediante un identificador de sesión único. Pueden utilizarse
   para persistir información entre varias páginas. Los identificadores de sesión
   se envían normalmente al navegador a través de cookies de sesión, y el identificador
   se utiliza para recuperar los datos existentes de la sesión. La ausencia de un identificador
   o de una cookie de sesión indica a PHP que debe crear una nueva sesión, generando así
   un nuevo identificador de sesión.
  </para>
  <para>
   Las sesiones siguen una cinemática simple. Cuando se inicia una sesión, PHP
   recuperará una sesión existente utilizando el identificador de sesión pasado (habitualmente
   desde una cookie de sesión) o, si no se pasa ningún identificador de sesión, creará una
   nueva sesión. PHP poblará entonces la variable superglobal <varname>$_SESSION</varname>
   con todos los datos de la sesión una vez iniciada. Cuando PHP finaliza,
   tomará automáticamente el contenido de la variable superglobal <varname>$_SESSION</varname>,
   lo serializará y lo enviará para su almacenamiento al gestor de guardado de sesión.
  </para>
  <para>
   Por omisión, PHP utiliza internamente el gestor de guardado <parameter>files</parameter>
   que está definido mediante la directiva <link linkend="ini.session.save-handler">session.save_handler</link>.
   Los datos de sesión se guardarán en el servidor en el lugar especificado por
   la directiva de configuración <link linkend="ini.session.save-path">session.save_path</link>.
  </para>
  <para>
   Las sesiones pueden iniciarse manualmente utilizando la función
   <function>session_start</function>. Si la directiva de configuración
   <link linkend="ini.session.auto-start">session.auto_start</link> está definida como
   <parameter>1</parameter>, una sesión se iniciará automáticamente al comienzo
   de la solicitud.
  </para>
  <para>
   Las sesiones se detienen automáticamente cuando PHP ha terminado de ejecutar un script, pero
   pueden detenerse manualmente utilizando la función
   <function>session_write_close</function>.
  </para>
  <para>
   <example>
    <title>
     Almacenar una variable con <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>
     Eliminar una variable de sesión con la superglobal <varname>$_SESSION</varname>.
    </title>
    <programlisting role="php">
     <![CDATA[
<?php
session_start();
unset($_SESSION['count']);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <caution>
    <para>
     No utilice la función <function>unset</function>
     con <varname>$_SESSION</varname> de la forma
     <literal>unset($_SESSION)</literal> ya que esto hará imposible
     el almacenamiento de datos en la sesión utilizando la superglobal
     <varname>$_SESSION</varname>.
    </para>
   </caution>
  </para>
  <warning>
   <para>
    No se pueden utilizar referencias en variables de sesión
    ya que no hay ninguna manera factible de restaurar una referencia a otra
    variable.
   </para>
  </warning>
  <note>
   <para>
    Las sesiones basadas en ficheros (por omisión en PHP) bloquean
    el fichero de sesión cuando una sesión se abre mediante la función
    <function>session_start</function> o implícitamente mediante la directiva
    de configuración <link linkend="ini.session.auto-start">session.auto_start</link>.
    Una vez bloqueado, ningún otro script puede acceder al mismo fichero
    de sesión hasta que la sesión no haya sido cerrada por el script
    que la abrió, o hasta que la función
    <function>session_write_close</function> no haya sido llamada.
   </para>
   <para>
    Esto puede ser problemático para los sitios web que utilizan AJAX y producen
    múltiples solicitudes concurrentes. La forma más sencilla de evitar
    este problema es llamar a la función <function>session_write_close</function>
    una vez que se hayan realizado los cambios en la sesión,
    preferiblemente al principio del script. También se puede utilizar
    otro gestor de sesión que soporte concurrencia.
   </para>
  </note>
 </section>

 <section xml:id="session.idpassing">
  <title>Pasar el identificador de sesión (session ID)</title>
  <para>
   Existen dos métodos de propagación del identificador de sesión:
   <itemizedlist>
    <listitem>
     <simpara>
      Cookies
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Por URL
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   El módulo de sesión soporta ambos métodos. Las cookies son
   óptimas, pero como no son seguras (no todos los internautas
   las aceptan), no son fiables. El segundo
   método coloca el identificador de sesión directamente en las URL.
  </para>
  <para>
   PHP es capaz de hacerlo de manera transparente.
   Si la opción de compilación
   <literal>session.use_trans_sid</literal> está activada,
   las URL relativas se modificarán para contener el identificador
   de sesión automáticamente.
   <note>
    <para>
     La opción <link linkend="ini.arg-separator.output">arg_separator.output</link>
     de &php.ini; permite personalizar el separador de argumentos.
     Para estar completamente de acuerdo con las especificaciones XHTML, especifique
     &amp;amp; aquí.
    </para>
   </note>
  </para>
  <para>
   Alternativamente, se puede utilizar la constante <constant>SID</constant>
   que está definida si la sesión ha comenzado. Si el cliente no envía una cookie de sesión
   apropiada, tendrá la forma <literal>session_name=session_id</literal>.
   De lo contrario, valdrá una cadena vacía. Así, en todos los casos
   se puede incluir en la URL.
  </para>
  <para>
   El siguiente ejemplo muestra cómo almacenar una variable y cómo
   realizar un enlace correcto a otra página, con
   <constant>SID</constant>.
   <example>
    <title>Contar el número de visitas de un usuario a una página</title>
    <programlisting role="php">
     <![CDATA[
<?php

session_start();

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

<p>
 Hola visitante, ha visto esta página <?php echo $_SESSION['count']; ?> veces.
</p>

<p>
 Para continuar, <a href="nextpage.php?<?php echo htmlspecialchars(SID); ?>">haga clic aquí</a>.
</p>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   La función <function>htmlspecialchars</function> se utiliza al mostrar
   el <constant>SID</constant> con el fin de contrarrestar los ataques XSS.
  </para>
  <para>
   La visualización del <constant>SID</constant>, como se muestra en el ejemplo
   anterior, no es necesaria si <link
   linkend="ini.session.use-trans-sid">
   --enable-trans-sid</link> se ha utilizado para compilar
   PHP.
  </para>
  <note>
   <para>
    Las URL no relativas se consideran externas al sitio y no
    recibirán el <constant>SID</constant>, ya que la fuga del <constant>SID</constant>
    a un servidor diferente presenta un riesgo de seguridad importante.
   </para>
  </note>
 </section>

 <section xml:id="session.customhandler">
  <title>Gestión personalizada de sesiones</title>
  <para>
   Para implementar un almacenamiento en base de datos, u otro método,
   se necesitará la función <function>session_set_save_handler</function> para
   configurar las propias funciones de almacenamiento.
   Un gestor de sesión puede crearse utilizando la interfaz
   <classname>SessionHandlerInterface</classname> o extendiendo los
   gestores internos de PHP heredando de la clase
   <classname>SessionHandler</classname>.
  </para>
  <para>
   Las funciones de retrollamada especificadas en <function>session_set_save_handler</function> son
   métodos llamados por PHP durante el ciclo de vida de la sesión: <parameter>open</parameter>,
   <parameter>read</parameter>, <parameter>write</parameter> y <parameter>close</parameter>
   así como las funciones de mantenimiento <parameter>destroy</parameter> para eliminar una sesión
   y <parameter>gc</parameter> para una recolección periódica de patrones.
  </para>
  <para>
   Así, PHP siempre necesita un gestor de sesiones. Por omisión se trata del gestor
   interno 'files'. Un gestor personalizado puede indicarse mediante
   <function>session_set_save_handler</function>. Otros gestores alternativos pueden ser propuestos
   por extensiones PHP, como <parameter>sqlite</parameter>, <parameter>memcache</parameter>
   y <parameter>memcached</parameter> y pueden utilizarse mediante
   <link linkend="ini.session.save-handler">session.save_handler</link>.
  </para>
  <para>
   Cuando la sesión comienza, PHP llamará internamente a la función <parameter>open</parameter> del gestor, seguida de
   <parameter>read</parameter> que debe entonces devolver una cadena codificada exactamente como fue pasada durante el almacenamiento.
   Una vez que la función de retrollamada de <parameter>read</parameter> haya devuelto su cadena, PHP la decodificará
   y poblará la superglobal <varname>$_SESSION</varname> en consecuencia.
  </para>
  <para>
   Cuando PHP finaliza (o cuando <function>session_write_close</function> es llamada), codificará internamente el contenido de <varname>$_SESSION</varname> y lo pasará con el ID de sesión a la
   función <parameter>write</parameter>. Después de <parameter>write</parameter>, PHP invocará <parameter>close</parameter>.
  </para>
  <para>
   Cuando una sesión es destruida, PHP llamará a <parameter>destroy</parameter> con el ID de sesión.
  </para>
  <para>
   PHP llamará a la función de retrollamada <parameter>gc</parameter> de vez en cuando para limpiar
   las sesiones expiradas según su
   tiempo de vida máximo. Esta llamada debería llevar a la destrucción de los registros en
   el soporte de almacenamiento que no han sido accedidos desde <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
 -->