-
Notifications
You must be signed in to change notification settings - Fork 60
Expand file tree
/
Copy pathexamples.xml
More file actions
280 lines (272 loc) · 10.8 KB
/
examples.xml
File metadata and controls
280 lines (272 loc) · 10.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
<?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; 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
-->