[PHP-DOC] cvs: phpdoc-es /reference/session reference.xml

[Rafael Martinez]

rafael          Sat May 25 12:40:16 2002 EDT

  Added files:                 
    /phpdoc-es/reference/session        reference.xml 
  Log:
  Translation updated to PHP 4.x
  
  


Index: phpdoc-es/reference/session/reference.xml
+++ phpdoc-es/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
-->