php-doc-en/reference/session/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>

 <reference id="ref.session">
  <title>Funciones para el manejo de sesiones</title>
  <titleabbrev>Sesiones</titleabbrev>
	
  <partintro>
   <para>
    El apoyo que PHP proporciona para las sesiones consiste en una forma de
	conservar ciertos datos a lo largo de los subsiguientes accesos, lo cual
	le permite construir aplicaciones m&aacute;s personalizadas e incrementar el
	atractivo de su sitio web.
   </para>
   <para>
    Si ya est&aacute; familiarizado con el tratamiento de sesiones de PHPLIB,
	notar&aacute; que algunos conceptos son similares al soporte de las sesiones
	de PHP.
   </para>
   <para>
    A cada visitante que accede a su web se le asigna un identificador &uacute;nico,
	llamado "session id" (identificador de sesi&oacute;n). &Eacute;ste se almacena
	en una cookie por parte del usuario o se propaga en la URL.
   </para>
   <para>
    El soporte de las sesiones le permite registrar un n&uacute;mero arbitrario de
	variables que se conservar&aacute;n en las siguientes peticiones. Cuando un
	visitante acceda a su web, PHP comprobar&aacute; autom&aacute;ticamente (si
	session.auto_start est&aacute; puesto a 1) o cuando usted lo especifique (de forma
	expl&iacute;cita mendiante <function>session_start</function> o impl&iacute;cita a trav&eacute;s
	de <function>session_register</function>) si se le ha enviado un "session id"
	espec&iacute;fico con su petici&oacute;n, en cuyo caso se recrean las variables que se
	hab&iacute;an guardado anteriormente.
   </para>
   <para>
    Todas las variables registradas son almacenadas tras finalizar la petici&oacute;n.
	Las variables que est&aacute;n indefinidas se marcan como no definidas. En los
	subsiguientes accesos, no estar&aacute;n definidas por el m&oacute;dulo de sesiones a
	menos que el usuario las defina m&aacute;s tarde.
   </para>
   <para>
    Las opciones de configuraci&oacute;n <link
    linkend="ini.track-vars"><literal>track_vars</literal></link> y <link
    linkend="ini.register-globals"><literal>register_globals</literal></link> influyen
	notablemente en la forma en que las variables de la sesi&oacute;n se almacenan
	y restauran.
   </para>

   <note>
    <para>
     A partir de PHP 4.0.3, <link
     linkend="ini.track-vars"><literal>track_vars</literal></link> siempre est&aacute; activado.
    </para>
   </note>
   <note>
    <para>
	 A partir de PHP 4.1.0, <varname>$_SESSION</varname> est&aacute; disponible como
	 variable global, al igual que <varname>$_POST</varname>, <varname>$_GET</varname>,
	 <varname>$_REQUEST</varname> y dem&aacute;s. Al contrario que
	 <varname>$HTTP_SESSION_VARS</varname>, <varname>$_SESSION</varname> siempre es
	 global. Por tanto, no se debe usar global para <varname>$_SESSION</varname>.
    </para>
   </note>

   <para>
    Si <link linkend="ini.track-vars"><literal>track_vars</literal></link> est&aacute; activado y
	<link linkend="ini.register-globals"><literal>register_globals</literal></link> est&aacute;
	desactivado, s&oacute;lo los miembros del vector asociativo global
	<varname>$HTTP_SESSION_VARS</varname> pueden ser registrados como variables de
	la sesi&oacute;n. Las variables restauradas de la sesi&oacute;n s&oacute;lo estar&aacute;n disponibles en
	el vector <varname>$HTTP_SESSION_VARS</varname>.
  <example>
     <title>
      Registrar una variable con <link
      linkend="ini.track-vars"><literal>track_vars</literal></link>
      activado
     </title>
     <programlisting role="php">
<![CDATA[
<?php
session_start();
if (isset($HTTP_SESSION_VARS['count'])) {
   $HTTP_SESSION_VARS['count']++;
}
else {
   $HTTP_SESSION_VARS['count'] = 0;
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Se recomienda usar <varname>$_SESSION</varname> (o
	<varname>$HTTP_SESSION_VARS</varname> con PHP 4.0.6 o inferior) por seguridad
	y para hacer el c&oacute;digo m&aacute;s legible. Con <varname>$_SESSION</varname> o
	<varname>$HTTP_SESSION_VARS</varname>, no es necesario usar las funciones
	session_register() / session_unregister() / session_is_registered(). Los usuarios
	pueden acceder a una variable de la sesi&oacute;n como si se tratase de una variable
	normal.
    <example>
     <title>
      Registrar una variable con $_SESSION.
     </title>
     <programlisting role="php">
<![CDATA[
<?php
session_start();
// Use $HTTP_SESSION_VARS con PHP 4.0.6 o inferior
if (!isset($_SESSION['count'])) {
    $_SESSION['count'] = 0;
} else {
    $_SESSION['count']++;
}
?>
]]>
     </programlisting>
    </example>
    <example>
     <title>
      Borrar una variable con $_SESSION.
     </title>
     <programlisting role="php">
<![CDATA[
<?php
session_start();
// Use $HTTP_SESSION_VARS con PHP 4.0.6 o inferior
unset($_SESSION['count']);
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Si <link linkend="ini.register-globals"><literal>register_globals</literal></link>
	est&aacute; activado, todas las variables globales pueden ser registradas como
	variables de la sesi&oacute;n, y las variables de la sesi&oacute;n ser&aacute;n restauradas a sus
	correspondientes variables globales. Como PHP debe saber qu&eacute; variables
	globles est&aacute;n registradas como variables de la sesi&oacute;n, los usuarios deben
	registrar las variables con la funci&oacute;n session_register(), mientras que con
	<varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> no es
	necesario usar session_register().
    <caution>
     <para>
      Si est&aacute; usando
      <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>
      y desactiva <link
      linkend="ini.register-globals"><literal>register_globals</literal></link>,
      no use <function>session_register</function>,
      <function>session_is_registered</function> ni
      <function>session_unregister</function>.
     </para>
     <para>
      Si activa <link
       linkend="ini.register-globals"><literal>register_globals</literal></link>,
       <function>session_unregister</function> deber&iacute;a ser usado a partir de
	   que las variables de la sesi&oacute;n sean registradas como variables
	   globales cuando los datos de la sesi&oacute;n se guardan. Se recomienda
	   desactivar <link linkend="ini.register-globals"><literal>register_globals</literal></link>
	   por motivos de seguridad y rendimiendo.
     </para>
    </caution>
    <example>
     <title>
      Registrar una variable con <link
      linkend="ini.register-globals"><literal>register_globals</literal></link>
      activado
     </title>
     <programlisting role="php">
<![CDATA[
<?php
if (!session_is_registered('count')) {
    session_register("count");
    $count = 0;
}
else {
    $count++;
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Si <link linkend="ini.track-vars"><literal>track_vars</literal></link> y
	<link linkend="ini.register-globals"><literal>register_globals</literal></link>
	est&aacute;n activados, las variables globales y las entradas de
	<varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> har&aacute;n
	referencia al mismo valor para variables ya registradas.
   </para>
   <para>
    Si el usuario utiliza session_register() para registrar una variable, el
	vector <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>
	no contendr&aacute; esa variable hasta que se cargue de los datos de la sesi&oacute;n.
	(p.ej. hasta la pr&oacute;xima petici&oacute;n).
   </para>
   <para>
    Hay dos formas de propagar un "session id":
    <itemizedlist>
     <listitem>
      <simpara>
       Cookies
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Par&aacute;metro en la URL
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    El m&oacute;dulo de sesiones admite ambas formas. Las Cookies son la mejor
	opci&oacute;n, pero como no son fiables (los clientes no est&aacute;n obligados a aceptarlas),
	no podemos confiar en ellas. El segundo m&eacute;todo incrusta el "session id"
	directamente en las URLs.
   </para>
   <para>
    PHP es capaz de hacerlo de forma transparente al usuario cuando se compila con
	<link linkend="install.configure.enable-trans-sid">
    <literal>--enable-trans-sid</literal></link>. Si activa esta opci&oacute;n, las URIs relativas
	ser&aacute;n modificadas de forma que contengan el session id autom&aacute;ticamente.
	Alternativamente, puede usar la constante <literal>SID</literal> que est&aacute;
	definida, si el cliente no env&iacute;a la cookie adecuada. El <literal>SID</literal>
	puede tener la forma de <literal>nombre_de_sesion=session_id</literal> o ser
	una cadena vac&iacute;a.
   </para>
   <para>
    El ejemplo siguiente demuestra c&oacute;mo registrar una variable, y c&oacute;mo colocar
	correctamente un enlace a otra p&aacute;gina usando la constante SID.
    <example>
     <title>Contar el n&uacute;mero de impresiones de un usuario</title>
     <programlisting role="php">
<![CDATA[
<?php
if (!session_is_registered('count')) {
    session_register('count');
    $count = 1;
}
else {
    $count++;
}
?>

Hola, visitante. Has visto esta p&aacute;gina <?php echo $count; ?> veces.

<?php
# el <?php echo SID?> (Se puede usar <?=SID?> si short tag est&aacute; activado)
# es necesario para conservar el session id
# en caso de que el usuario haya desactivado las cookies
?>

Para continuar, haga click <A HREF="nextpage.php?<?php echo SID?>">aqu&iacute;</A>.
]]>
     </programlisting>
    </example>
   </para>
   <para>
    El <literal>&lt;?=SID?&gt;</literal> no es necesario si se ha usado
    <link linkend="install.configure.enable-trans-sid">
    <literal>--enable-trans-sid</literal></link> al compilar PHP.
   </para>
   <note>
    <para>
     Se asume que las URLs no relativas apuntan a sitios web externos,
	 y por tanto no se a&ntilde;ade el SID, ya que pasar el SID a un servidor
	 diferente podr&iacute;a ocasionar un agujero de seguridad.
    </para>
   </note>
   <para>
    Para implementar el almacenamiento en bases de datos o en otro tipo
	de almacenamiento, necesitar&aacute; usar
	<function>session_set_save_handler()</function> para crear una
	colecci&oacute;n de funciones de almacenamiento a nivel de usuario.
   </para>
   <para>
    El sistema de control de sesiones soporta varias opciones de
	configuraci&oacute;n que puede colocar en su archivo &php.ini;. Les daremos
	un peque&ntilde;o repaso.
    <itemizedlist>
     <listitem>
      <simpara>
       <literal>session.save_handler</literal> define el nombre del
	   controlador que se usa para almacenar y recuperar los datos
	   asociados a la sesi&oacute;n. Su valor por defecto es <literal>files</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.save_path</literal> define el argumento que se
	   pasa al controlador de almacenamiento. Si elige el controlador de
	   archivos por defecto, esta es la ruta donde los archivos se crean.
	   Por defecto es <literal>/tmp</literal>. Si la profundidad de la
	   ruta de <literal>session.save_path</literal> es mayor que 2, no se
	   llevar&aacute; a cabo la recolecci&oacute;n de basura.
      </simpara>
      <warning>
       <para>
	    Si lo deja apuntando a un directorio con permiso de lectura por el
		resto de usuarios, como <filename>/tmp</filename> (la opci&oacute;n por
		defecto), los dem&aacute;s usuarios del servidor pueden conseguir robar
		las sesiones obteni&eacute;ndolas de la lista de archivos de ese directorio.
       </para>
      </warning>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.name</literal> especifica el nombre de la sesi&oacute;n que
	   se usa como nombre de la cookie. S&oacute;lo deber&iacute;a contener caracteres
	   alfanum&eacute;ricos. Por defecto vale <literal>PHPSESSID</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.auto_start</literal> especifica si el m&oacute;dulo de las
	   sesi&oacute;n inicia una sesi&oacute;n autom&aacute;ticamente al comenzar la petici&oacute;n. Por
	   defecto est&aacute; <literal>0</literal> (desactivado).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.cookie_lifetime</literal> especifica la duraci&oacute;n de
	   la cookie en segundos que se manda al navegador. El valor
	   <literal>0</literal> significa "hasta que se cierra el navegador", y
	   es el que se encuentra por defecto.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.serialize_handler</literal> define el nombre del
	   controlador que se utiliza para guardar y restaurar los datos.
	   Actualmente se soportan un formato interno de PHP (cuyo nombre es
	   <literal>php</literal>) y WDDX (cuyo nombre es
	   <literal>wddx</literal>). WDDX s&oacute;lo est&aacute; disponible si PHP est&aacute;
	   compilado con <link linkend="ref.wddx">Soporte para WDDX</link>. Por
	   defecto es <literal>php</literal>.
       </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.gc_probability</literal> especifica la probabilidad
	   de que se inicie la rutina gc (garbage collection - recoleci&oacute;n de
	   basura) en cada petici&oacute;n en porcentaje. Por defecto es <literal>1</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.gc_maxlifetime</literal> especifica el n&uacute;mero de segundos
	   tras los cuales los datos se considerar&aacute;n como 'basura' y ser&aacute;n
	   eliminados.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.referer_check</literal> contiene la subcadena que usted
	   quiera que se compruebe en cada "HTTP Referer" (N.T.: P&aacute;gina desde donde
	   proviene el enlace a la p&aacute;gina actual). Si el "Referer" fue enviado por
	   el cliente y la subcadena no se ha encontrado, el session id incrustado
	   ser&aacute; marcado como inv&aacute;lido. Por defecto es una cadena vac&iacute;a.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.entropy_file</literal> indica la ruta a un recurso
	   externo (un archivo) que se usar&aacute; como fuente adicional de entrop&iacute;a
	   en el proceso de creaci&oacute;n de session id's. Por ejemplo
	   <literal>/dev/random</literal> o <literal>/dev/urandom</literal>,
	   que est&aacute;n disponibles en muchos sistemas Unix.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.entropy_length</literal> especifica el n&uacute;mero
	   de bytes que ser&aacute;n leidos del archivo indicado m&aacute;s arriba. Por
	   defecto es <literal>0</literal> (desactivado).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.use_cookies</literal> indica si el m&oacute;dulo
	   puede usar cookies para guardar el session id en el lado del
	   cliente. Por defecto est&aacute; a  <literal>1</literal> (activado).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.cookie_path</literal> especifica la ruta a
	   colocar en session_cookie. Por defecto es <literal>/</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.cookie_domain</literal> especifica el dominio
	   a establecer en session_cookie. Por defecto no se especifica
	   ninguno en ning&uacute;n caso. 
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.cache_limiter</literal> especifica el m&eacute;todo
	   de control del cach&eacute; a usar en las p&aacute;ginas de la sesi&oacute;n
	   (none/nocache/private/private_no_expire/public). Por defecto es
       <literal>nocache</literal> (no guardar las p&aacute;ginas en el cach&eacute;).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.cache_expire</literal> especifica el
	   tiempo-de-vida de las p&aacute;ginas de la sesi&oacute;n que se encuentran en
	   el cach&eacute; en minutos. No tiene efecto para el limitador nocache.
	   Por defecto vale <literal>180</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.use_trans_sid</literal> indica si la inclusi&oacute;n
	   del sid transparente est&aacute; activada o no, si fue activada
	   compilando con  <link linkend="install.configure.enable-trans-sid">
       <literal>--enable-trans-sid</literal></link>. Por defecto est&aacute; a
	   <literal>1</literal> (activado).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>url_rewriter.tags</literal> especifica qu&eacute; etiquetas
	   html ser&aacute;n reescritas para incluir el session id si la inclusi&oacute;n
	   del sid transparente est&aacute; activada. Las etiquetas por defecto son
	   <literal>a=href,area=href,frame=src,input=src,form=fakeentry</literal>
      </simpara>
     </listitem>
    </itemizedlist>
    <note>
     <para>
      El manejo de sesiones fue a&ntilde;adido en PHP 4.0.
     </para>
    </note>
   </para>
  </partintro>

&reference.session.functions;

 </reference>

<!-- 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:"../../../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
-->