rafael Sat May 25 12:35:24 2002 EDT Modified files: /phpdoc/en/reference/session reference.xml Log: Fix commit error Sorry :-(
Index: phpdoc/en/reference/session/reference.xml diff -u phpdoc/en/reference/session/reference.xml:1.4 phpdoc/en/reference/session/reference.xml:1.5 --- phpdoc/en/reference/session/reference.xml:1.4 Sat May 25 12:32:35 2002 +++ phpdoc/en/reference/session/reference.xml Sat May 25 12:35:24 2002 @@ -1,78 +1,83 @@ <?xml version="1.0" encoding="iso-8859-1"?> - +<!-- $Revision: 1.5 $ --> <reference id="ref.session"> - <title>Funciones para el manejo de sesiones</title> - <titleabbrev>Sesiones</titleabbrev> + <title>Session handling functions</title> + <titleabbrev>Sessions</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ás personalizadas e incrementar el - atractivo de su sitio web. + Session support in PHP consists of a way to preserve certain data + across subsequent accesses. This enables you to build more + customized applications and increase the appeal of your web site. </para> <para> - Si ya está familiarizado con el tratamiento de sesiones de PHPLIB, - notará que algunos conceptos son similares al soporte de las sesiones - de PHP. + If you are familiar with the session management of PHPLIB, you + will notice that some concepts are similar to PHP's session + support. </para> <para> - A cada visitante que accede a su web se le asigna un identificador único, - llamado "session id" (identificador de sesión). Éste se almacena - en una cookie por parte del usuario o se propaga en la URL. + A visitor accessing your web site is assigned an unique id, the + so-called session id. This is either stored in a cookie on the + user side or is propagated in the URL. </para> <para> - El soporte de las sesiones le permite registrar un número arbitrario de - variables que se conservarán en las siguientes peticiones. Cuando un - visitante acceda a su web, PHP comprobará automáticamente (si - session.auto_start está puesto a 1) o cuando usted lo especifique (de forma - explícita mendiante <function>session_start</function> o implícita a través - de <function>session_register</function>) si se le ha enviado un "session id" - específico con su petición, en cuyo caso se recrean las variables que se - habían guardado anteriormente. + The session support allows you to register arbitrary numbers of + variables to be preserved across requests. When a visitor accesses + your site, PHP will check automatically (if session.auto_start is + set to 1) or on your request (explicitly through + <function>session_start</function> or implicitly through + <function>session_register</function>) whether a specific session + id has been sent with the request. If this is the case, the prior + saved environment is recreated. </para> <para> - Todas las variables registradas son almacenadas tras finalizar la petición. - Las variables que están indefinidas se marcan como no definidas. En los - subsiguientes accesos, no estarán definidas por el módulo de sesiones a - menos que el usuario las defina más tarde. + All registered variables are serialized after the request + finishes. Registered variables which are undefined are marked as + being not defined. On subsequent accesses, these are not defined + by the session module unless the user defines them later. </para> <para> - Las opciones de configuració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ón se almacenan - y restauran. + The <link + linkend="ini.track-vars"><literal>track_vars</literal></link> and + <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + configuration settings influence how the session variables get + stored and restored. </para> <note> <para> - A partir de PHP 4.0.3, <link - linkend="ini.track-vars"><literal>track_vars</literal></link> siempre está activado. + As of PHP 4.0.3, <link + linkend="ini.track-vars"><literal>track_vars</literal></link> is + always turned on. </para> </note> <note> <para> - A partir de PHP 4.1.0, <varname>$_SESSION</varname> está disponible como - variable global, al igual que <varname>$_POST</varname>, <varname>$_GET</varname>, - <varname>$_REQUEST</varname> y demá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>. + As of PHP 4.1.0, <varname>$_SESSION</varname> is available as + global variable just like <varname>$_POST</varname>, + <varname>$_GET</varname>, <varname>$_REQUEST</varname> and so on. + Not like <varname>$HTTP_SESSION_VARS</varname>, + <varname>$_SESSION</varname> is always global. Therefore, + <literal>global</literal> should not be used for + <varname>$_SESSION</varname>. </para> </note> <para> - Si <link linkend="ini.track-vars"><literal>track_vars</literal></link> está activado y - <link linkend="ini.register-globals"><literal>register_globals</literal></link> está - desactivado, sólo los miembros del vector asociativo global - <varname>$HTTP_SESSION_VARS</varname> pueden ser registrados como variables de - la sesión. Las variables restauradas de la sesión sólo estarán disponibles en - el vector <varname>$HTTP_SESSION_VARS</varname>. + If <link + linkend="ini.track-vars"><literal>track_vars</literal></link> is + enabled and <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + is disabled, only members of the global associative array + <varname>$HTTP_SESSION_VARS</varname> can be registered as session + variables. The restored session variables will only be available + in the array <varname>$HTTP_SESSION_VARS</varname>. <example> <title> - Registrar una variable con <link + Registering a variable with <link linkend="ini.track-vars"><literal>track_vars</literal></link> - activado + enabled </title> <programlisting role="php"> <![CDATA[ @@ -90,22 +95,23 @@ </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ódigo má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ón como si se tratase de una variable - normal. + Use of <varname>$_SESSION</varname> (or + <varname>$HTTP_SESSION_VARS</varname> with PHP 4.0.6 or less) is + recommended for security and code readablity. With + <varname>$_SESSION</varname> or + <varname>$HTTP_SESSION_VARS</varname>, there is no need to use + session_register()/session_unregister()/session_is_registered() + functions. Users can access session variable like a normal + variable. <example> <title> - Registrar una variable con $_SESSION. + Registering a variable with $_SESSION. </title> <programlisting role="php"> <![CDATA[ <?php session_start(); -// Use $HTTP_SESSION_VARS con PHP 4.0.6 o inferior +// Use $HTTP_SESSION_VARS with PHP 4.0.6 or less if (!isset($_SESSION['count'])) { $_SESSION['count'] = 0; } else { @@ -117,13 +123,13 @@ </example> <example> <title> - Borrar una variable con $_SESSION. + Unregistering a variable with $_SESSION. </title> <programlisting role="php"> <![CDATA[ <?php session_start(); -// Use $HTTP_SESSION_VARS con PHP 4.0.6 o inferior +// Use $HTTP_SESSION_VARS with PHP 4.0.6 or less unset($_SESSION['count']); ?> ]]> @@ -131,39 +137,40 @@ </example> </para> <para> - Si <link linkend="ini.register-globals"><literal>register_globals</literal></link> - está activado, todas las variables globales pueden ser registradas como - variables de la sesión, y las variables de la sesión serán restauradas a sus - correspondientes variables globales. Como PHP debe saber qué variables - globles están registradas como variables de la sesión, los usuarios deben - registrar las variables con la función session_register(), mientras que con - <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> no es - necesario usar session_register(). + If <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + is enabled, then all global variables can be registered as session + variables and the session variables will be restored to + corresponding global variables. Since PHP must know which global + variables are registered as session variables, users must register + variables with session_register() function while + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> + does not need to use session_register(). <caution> <para> - Si está usando + If you are using <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> - y desactiva <link + and disable <link linkend="ini.register-globals"><literal>register_globals</literal></link>, - no use <function>session_register</function>, - <function>session_is_registered</function> ni + do not use <function>session_register</function>, + <function>session_is_registered</function> and <function>session_unregister</function>. </para> <para> - Si activa <link + If you enable <link linkend="ini.register-globals"><literal>register_globals</literal></link>, - <function>session_unregister</function> debería ser usado a partir de - que las variables de la sesión sean registradas como variables - globales cuando los datos de la sesión se guardan. Se recomienda - desactivar <link linkend="ini.register-globals"><literal>register_globals</literal></link> - por motivos de seguridad y rendimiendo. + <function>session_unregister</function> should be used since + session variables are registered as global variables when + session data is deserialized. Disabling <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + is recommended for both security and performance reason. </para> </caution> <example> <title> - Registrar una variable con <link + Registering a variable with <link linkend="ini.register-globals"><literal>register_globals</literal></link> - activado + enabled </title> <programlisting role="php"> <![CDATA[ @@ -181,20 +188,23 @@ </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án activados, las variables globales y las entradas de - <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> hará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á esa variable hasta que se cargue de los datos de la sesión. - (p.ej. hasta la próxima petición). + If both <link + linkend="ini.track-vars"><literal>track_vars</literal></link> and + <link + linkend="ini.register-globals"><literal>register_globals</literal></link> + are enabled, then the globals variables and the + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> + entries will reference the same value for already registered + variables. + </para> + <para> + If user use session_register() to register session variable, + <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname> + will not have these variable in array until it is loaded from + session storage. (i.e. until next request) </para> <para> - Hay dos formas de propagar un "session id": + There are two methods to propagate a session id: <itemizedlist> <listitem> <simpara> @@ -203,32 +213,33 @@ </listitem> <listitem> <simpara> - Parámetro en la URL + URL parameter </simpara> </listitem> </itemizedlist> </para> <para> - El módulo de sesiones admite ambas formas. Las Cookies son la mejor - opción, pero como no son fiables (los clientes no están obligados a aceptarlas), - no podemos confiar en ellas. El segundo mé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ón, las URIs relativas - serán modificadas de forma que contengan el session id automáticamente. - Alternativamente, puede usar la constante <literal>SID</literal> que está - definida, si el cliente no enví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ía. + The session module supports both methods. Cookies are optimal, but + since they are not reliable (clients are not bound to accept + them), we cannot rely on them. The second method embeds the + session id directly into URLs. + </para> + <para> + PHP is capable of doing this transparently when compiled with + <link linkend="install.configure.enable-trans-sid"> + <literal>--enable-trans-sid</literal></link>. If you enable this option, + relative URIs will be changed to contain the session id + automatically. Alternatively, you can use the constant + <literal>SID</literal> which is defined, if the client did not + send the appropriate cookie. <literal>SID</literal> is either of + the form <literal>session_name=session_id</literal> or is an empty + string. </para> <para> - El ejemplo siguiente demuestra cómo registrar una variable, y cómo colocar - correctamente un enlace a otra página usando la constante SID. + The following example demonstrates how to register a variable, and + how to link correctly to another page using SID. <example> - <title>Contar el número de impresiones de un usuario</title> + <title>Counting the number of hits of a single user</title> <programlisting role="php"> <![CDATA[ <?php @@ -241,196 +252,194 @@ } ?> -Hola, visitante. Has visto esta página <?php echo $count; ?> veces. +Hello visitor, you have seen this page <?php echo $count; ?> times.<p>; <?php -# el <?php echo SID?> (Se puede usar <?=SID?> si short tag está activado) -# es necesario para conservar el session id -# en caso de que el usuario haya desactivado las cookies +# the <?php echo SID?> (<?=SID?> can be used if short tag is enabled) +# is necessary to preserve the session id +# in the case that the user has disabled cookies ?> -Para continuar, haga click <A HREF="nextpage.php?<?php echo SID?>">aquí</A>. +To continue, <A HREF="nextpage.php?<?php echo SID?>">click here</A> ]]> </programlisting> </example> </para> <para> - El <literal><?=SID?></literal> no es necesario si se ha usado + The <literal><?=SID?></literal> is not necessary, if <link linkend="install.configure.enable-trans-sid"> - <literal>--enable-trans-sid</literal></link> al compilar PHP. + <literal>--enable-trans-sid</literal></link> was used to compile PHP. </para> <note> <para> - Se asume que las URLs no relativas apuntan a sitios web externos, - y por tanto no se añade el SID, ya que pasar el SID a un servidor - diferente podría ocasionar un agujero de seguridad. + Non-relative URLs are assumed to point to external sites and + hence don't append the SID, as it would be a security risk to + leak the SID to a different server. </para> </note> <para> - Para implementar el almacenamiento en bases de datos o en otro tipo - de almacenamiento, necesitará usar - <function>session_set_save_handler()</function> para crear una - colección de funciones de almacenamiento a nivel de usuario. + To implement database storage, or any other storage method, you + will need to use <function>session_set_save_handler</function> to + create a set of user-level storage functions. </para> <para> - El sistema de control de sesiones soporta varias opciones de - configuración que puede colocar en su archivo &php.ini;. Les daremos - un pequeño repaso. + The session management system supports a number of configuration + options which you can place in your &php.ini; file. We will give a + short overview. <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ón. Su valor por defecto es <literal>files</literal>. + <literal>session.save_handler</literal> defines the name of the + handler which is used for storing and retrieving data + associated with a session. Defaults to + <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á a cabo la recolección de basura. + <literal>session.save_path</literal> defines the argument which + is passed to the save handler. If you choose the default files + handler, this is the path where the files are created. + Defaults to <literal>/tmp</literal>. If + <literal>session.save_path</literal>'s path depth is more than + 2, garbage collection will not be performed. </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ón por - defecto), los demás usuarios del servidor pueden conseguir robar - las sesiones obteniéndolas de la lista de archivos de ese directorio. + If you leave this set to a world-readable directory, such as + <filename>/tmp</filename> (the default), other users on the + server may be able to hijack sessions by getting the list of + files in that directory. </para> </warning> </listitem> <listitem> <simpara> - <literal>session.name</literal> especifica el nombre de la sesión que - se usa como nombre de la cookie. Sólo debería contener caracteres - alfanuméricos. Por defecto vale <literal>PHPSESSID</literal>. + <literal>session.name</literal> specifies the name of the + session which is used as cookie name. It should only contain + alphanumeric characters. Defaults to + <literal>PHPSESSID</literal>. </simpara> </listitem> <listitem> <simpara> - <literal>session.auto_start</literal> especifica si el módulo de las - sesión inicia una sesión automáticamente al comenzar la petición. Por - defecto está <literal>0</literal> (desactivado). + <literal>session.auto_start</literal> specifies whether the + session module starts a session automatically on request + startup. Defaults to <literal>0</literal> (disabled). </simpara> </listitem> <listitem> <simpara> - <literal>session.cookie_lifetime</literal> especifica la duració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. + <literal>session.cookie_lifetime</literal> specifies the lifetime of + the cookie in seconds which is sent to the browser. The value 0 + means "until the browser is closed." Defaults to + <literal>0</literal>. </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ólo está disponible si PHP está - compilado con <link linkend="ref.wddx">Soporte para WDDX</link>. Por - defecto es <literal>php</literal>. + <literal>session.serialize_handler</literal> defines the name + of the handler which is used to serialize/deserialize + data. Currently, a PHP internal format (name + <literal>php</literal>) and WDDX is supported (name + <literal>wddx</literal>). WDDX is only available, if PHP is + compiled with <link linkend="ref.wddx">WDDX + support</link>. Defaults to <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ón de - basura) en cada petición en porcentaje. Por defecto es <literal>1</literal>. + <literal>session.gc_probability</literal> specifies the + probability that the gc (garbage collection) routine is started + on each request in percent. Defaults to <literal>1</literal>. </simpara> </listitem> <listitem> <simpara> - <literal>session.gc_maxlifetime</literal> especifica el número de segundos - tras los cuales los datos se considerarán como 'basura' y serán - eliminados. + <literal>session.gc_maxlifetime</literal> specifies the number + of seconds after which data will be seen as 'garbage' and + cleaned up. </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ágina desde donde - proviene el enlace a la página actual). Si el "Referer" fue enviado por - el cliente y la subcadena no se ha encontrado, el session id incrustado - será marcado como inválido. Por defecto es una cadena vacía. + <literal>session.referer_check</literal> contains the substring you + want to check each HTTP Referer for. If the Referer was sent by the + client and the substring was not found, the embedded session id will + be marked as invalid. Defaults to the empty string. </simpara> </listitem> <listitem> <simpara> - <literal>session.entropy_file</literal> indica la ruta a un recurso - externo (un archivo) que se usará como fuente adicional de entropía - en el proceso de creación de session id's. Por ejemplo - <literal>/dev/random</literal> o <literal>/dev/urandom</literal>, - que están disponibles en muchos sistemas Unix. + <literal>session.entropy_file</literal> gives a path to an + external resource (file) which will be used as an additional + entropy source in the session id creation process. Examples are + <literal>/dev/random</literal> or + <literal>/dev/urandom</literal> which are available on many + Unix systems. </simpara> </listitem> <listitem> <simpara> - <literal>session.entropy_length</literal> especifica el número - de bytes que serán leidos del archivo indicado más arriba. Por - defecto es <literal>0</literal> (desactivado). + <literal>session.entropy_length</literal> specifies the number + of bytes which will be read from the file specified + above. Defaults to <literal>0</literal> (disabled). </simpara> </listitem> <listitem> <simpara> - <literal>session.use_cookies</literal> indica si el módulo - puede usar cookies para guardar el session id en el lado del - cliente. Por defecto está a <literal>1</literal> (activado). + <literal>session.use_cookies</literal> specifies whether the + module will use cookies to store the session id on the client + side. Defaults to <literal>1</literal> (enabled). </simpara> </listitem> <listitem> <simpara> - <literal>session.cookie_path</literal> especifica la ruta a - colocar en session_cookie. Por defecto es <literal>/</literal>. + <literal>session.cookie_path</literal> specifies path to set + in session_cookie. Defaults to <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ún caso. + <literal>session.cookie_domain</literal> specifies domain to + set in session_cookie. Default is none at all. </simpara> </listitem> <listitem> <simpara> - <literal>session.cache_limiter</literal> especifica el método - de control del caché a usar en las páginas de la sesión - (none/nocache/private/private_no_expire/public). Por defecto es - <literal>nocache</literal> (no guardar las páginas en el caché). + <literal>session.cache_limiter</literal> specifies cache + control method to use for session pages + (none/nocache/private/private_no_expire/public). Defaults to + <literal>nocache</literal>. </simpara> </listitem> <listitem> <simpara> - <literal>session.cache_expire</literal> especifica el - tiempo-de-vida de las páginas de la sesión que se encuentran en - el caché en minutos. No tiene efecto para el limitador nocache. - Por defecto vale <literal>180</literal>. + <literal>session.cache_expire</literal> specifies time-to-live + for cached session pages in minutes, this has no effect for + nocache limiter. Defaults to <literal>180</literal>. </simpara> </listitem> <listitem> <simpara> - <literal>session.use_trans_sid</literal> indica si la inclusión - del sid transparente está activada o no, si fue activada - compilando con <link linkend="install.configure.enable-trans-sid"> - <literal>--enable-trans-sid</literal></link>. Por defecto está a - <literal>1</literal> (activado). + <literal>session.use_trans_sid</literal> whether transparent sid support + is enabled or not if enabled by compiling with + <link linkend="install.configure.enable-trans-sid"> + <literal>--enable-trans-sid</literal></link>. + Defaults to <literal>1</literal> (enabled). </simpara> </listitem> <listitem> <simpara> - <literal>url_rewriter.tags</literal> especifica qué etiquetas - html serán reescritas para incluir el session id si la inclusión - del sid transparente está activada. Las etiquetas por defecto son - <literal>a=href,area=href,frame=src,input=src,form=fakeentry</literal> + <literal>url_rewriter.tags</literal> spefifies which html tags are + rewritten to include session id if transparent sid support is enabled. + Defaults to +<literal>a=href,area=href,frame=src,input=src,form=fakeentry</literal> </simpara> </listitem> </itemizedlist> <note> <para> - El manejo de sesiones fue añadido en PHP 4.0. + Session handling was added in PHP 4.0. </para> </note> </para>