reference/session/functions/session-set-save-handler.xml
184f3f7bd45643cb80f828d0bb001991ec3a5fad
...
...
@@ -1,11 +1,10 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler">
3
+
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>session_set_save_handler</refname>
6
6
<refpurpose>Sets user-level session storage functions</refpurpose>
7
7
</refnamediv>
8
-

9
8
<refsect1 role="description">
10
9
&reftitle.description;
11
10
<methodsynopsis>
...
...
@@ -17,21 +16,23 @@
17
16
<methodparam><type>callable</type><parameter>destroy</parameter></methodparam>
18
17
<methodparam><type>callable</type><parameter>gc</parameter></methodparam>
19
18
<methodparam choice="opt"><type>callable</type><parameter>create_sid</parameter></methodparam>
19
+
<methodparam choice="opt"><type>callable</type><parameter>validate_sid</parameter></methodparam>
20
+
<methodparam choice="opt"><type>callable</type><parameter>update_timestamp</parameter></methodparam>
20
21
</methodsynopsis>
21
22
<para>
22
-
Since PHP 5.4 it is possible to register the following prototype:
23
+
It is possible to register the following prototype:
23
24
</para>
24
25
<methodsynopsis>
25
26
<type>bool</type><methodname>session_set_save_handler</methodname>
26
-
<methodparam><type>SessionHandlerInterface</type><parameter>sessionhandler</parameter></methodparam>
27
-
<methodparam choice="opt"><type>bool</type><parameter>register_shutdown</parameter><initializer>true</initializer></methodparam>
27
+
<methodparam><type>object</type><parameter>sessionhandler</parameter></methodparam>
28
+
<methodparam choice="opt"><type>bool</type><parameter>register_shutdown</parameter><initializer>&true;</initializer></methodparam>
28
29
</methodsynopsis>
29
30
<para>
30
31
<function>session_set_save_handler</function> sets the user-level
31
32
session storage functions which are used for storing and
32
33
retrieving data associated with a session. This is most useful
33
34
when a storage method other than those supplied by PHP sessions
34
-
is preferred. i.e. Storing the session data in a local database.
35
+
is preferred, e.g. storing the session data in a local database.
35
36
</para>
36
37
</refsect1>
37
38

...
...
@@ -45,9 +46,11 @@
45
46
<listitem>
46
47
<para>
47
48
An instance of a class implementing
48
-
<interfacename>SessionHandlerInterface</interfacename>, such as
49
+
<interfacename>SessionHandlerInterface</interfacename>, and optionally
50
+
<interfacename>SessionIdInterface</interfacename> and/or
51
+
<interfacename>SessionUpdateTimestampHandlerInterface</interfacename>, such as
49
52
<classname>SessionHandler</classname>, to register as the session
50
-
handler. Since PHP 5.4 only.
53
+
handler.
51
54
</para>
52
55
</listitem>
53
56
</varlistentry>
...
...
@@ -66,9 +69,17 @@
66
69

67
70
<variablelist>
68
71
<varlistentry>
69
-
<term><parameter>open(string $savePath, string $sessionName)</parameter></term>
72
+
<term><parameter>open</parameter></term>
70
73
<listitem>
71
74
<para>
75
+
A callable with the following signature:
76
+
<methodsynopsis>
77
+
<type>bool</type><methodname><replaceable>open</replaceable></methodname>
78
+
<methodparam><type>string</type><parameter>savePath</parameter></methodparam>
79
+
<methodparam><type>string</type><parameter>sessionName</parameter></methodparam>
80
+
</methodsynopsis>
81
+
</para>
82
+
<para>
72
83
The open callback works like a constructor in classes and is
73
84
executed when the session is being opened. It is the first callback
74
85
function executed when the session is started automatically or
...
...
@@ -78,9 +89,16 @@
78
89
</listitem>
79
90
</varlistentry>
80
91
<varlistentry>
81
-
<term><parameter>close()</parameter></term>
92
+
<term><parameter>close</parameter></term>
82
93
<listitem>
83
94
<para>
95
+
A callable with the following signature:
96
+
<methodsynopsis>
97
+
<type>bool</type><methodname><replaceable>close</replaceable></methodname>
98
+
<void/>
99
+
</methodsynopsis>
100
+
</para>
101
+
<para>
84
102
The close callback works like a destructor in classes and is
85
103
executed after the session write callback has been called. It is also invoked when
86
104
<function>session_write_close</function> is called.
...
...
@@ -89,9 +107,16 @@
89
107
</listitem>
90
108
</varlistentry>
91
109
<varlistentry>
92
-
<term><parameter>read(string $sessionId)</parameter></term>
110
+
<term><parameter>read</parameter></term>
93
111
<listitem>
94
112
<para>
113
+
A callable with the following signature:
114
+
<methodsynopsis>
115
+
<type>string</type><methodname><replaceable>read</replaceable></methodname>
116
+
<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
117
+
</methodsynopsis>
118
+
</para>
119
+
<para>
95
120
The <parameter>read</parameter> callback must always return a session encoded (serialized)
96
121
string, or an empty string if there is no data to read.
97
122
</para>
...
...
@@ -105,14 +130,22 @@
105
130
passed for storage to the <parameter>write</parameter> callback. The value returned will be
106
131
unserialized automatically by PHP and used to populate the <varname>$_SESSION</varname> superglobal.
107
132
While the data looks similar to <function>serialize</function> please note it is a different format
108
-
which is speficied in the <link linkend="ini.session.serialize-handler">session.serialize_handler</link> ini setting.
133
+
which is specified in the <link linkend="ini.session.serialize-handler">session.serialize_handler</link> ini setting.
109
134
</para>
110
135
</listitem>
111
136
</varlistentry>
112
137
<varlistentry>
113
-
<term><parameter>write(string $sessionId, string $data)</parameter></term>
138
+
<term><parameter>write</parameter></term>
114
139
<listitem>
115
140
<para>
141
+
A callable with the following signature:
142
+
<methodsynopsis>
143
+
<type>bool</type><methodname><replaceable>write</replaceable></methodname>
144
+
<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
145
+
<methodparam><type>string</type><parameter>data</parameter></methodparam>
146
+
</methodsynopsis>
147
+
</para>
148
+
<para>
116
149
The <parameter>write</parameter> callback is called when the session needs to be saved and closed. This
117
150
callback receives the current session ID a serialized version the <varname>$_SESSION</varname> superglobal. The serialization
118
151
method used internally by PHP is specified in the <link linkend="ini.session.serialize-handler">session.serialize_handler</link> ini setting.
...
...
@@ -138,9 +171,16 @@
138
171
</listitem>
139
172
</varlistentry>
140
173
<varlistentry>
141
-
<term><parameter>destroy($sessionId)</parameter></term>
174
+
<term><parameter>destroy</parameter></term>
142
175
<listitem>
143
176
<para>
177
+
A callable with the following signature:
178
+
<methodsynopsis>
179
+
<type>bool</type><methodname><replaceable>destroy</replaceable></methodname>
180
+
<methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
181
+
</methodsynopsis>
182
+
</para>
183
+
<para>
144
184
This callback is executed when a session is destroyed with <function>session_destroy</function> or with
145
185
<function>session_regenerate_id</function> with the destroy parameter set to &true;.
146
186
Return value should be &true; for success, &false; for failure.
...
...
@@ -148,9 +188,16 @@
148
188
</listitem>
149
189
</varlistentry>
150
190
<varlistentry>
151
-
<term><parameter>gc($lifetime)</parameter></term>
191
+
<term><parameter>gc</parameter></term>
152
192
<listitem>
153
193
<para>
194
+
A callable with the following signature:
195
+
<methodsynopsis>
196
+
<type>bool</type><methodname><replaceable>gc</replaceable></methodname>
197
+
<methodparam><type>int</type><parameter>lifetime</parameter></methodparam>
198
+
</methodsynopsis>
199
+
</para>
200
+
<para>
154
201
The garbage collector callback is invoked internally by PHP periodically in order to
155
202
purge old session data. The frequency is controlled by
156
203
<link linkend="ini.session.gc-probability">session.gc_probability</link> and <link linkend="ini.session.gc-divisor">session.gc_divisor</link>.
...
...
@@ -160,15 +207,59 @@
160
207
</listitem>
161
208
</varlistentry>
162
209
<varlistentry>
163
-
<term><parameter>create_sid()</parameter></term>
210
+
<term><parameter>create_sid</parameter></term>
164
211
<listitem>
165
212
<para>
213
+
A callable with the following signature:
214
+
<methodsynopsis>
215
+
<type>string</type><methodname><replaceable>create_sid</replaceable></methodname>
216
+
<void/>
217
+
</methodsynopsis>
218
+
</para>
219
+
<para>
166
220
This callback is executed when a new session ID is required. No
167
221
parameters are provided, and the return value should be a string that
168
222
is a valid session ID for your handler.
169
223
</para>
170
224
</listitem>
171
225
</varlistentry>
226
+
<varlistentry>
227
+
<term><parameter>validate_sid</parameter></term>
228
+
<listitem>
229
+
<para>
230
+
A callable with the following signature:
231
+
<methodsynopsis>
232
+
<type>bool</type><methodname><replaceable>validate_sid</replaceable></methodname>
233
+
<methodparam><type>string</type><parameter>key</parameter></methodparam>
234
+
</methodsynopsis>
235
+
</para>
236
+
<para>
237
+
This callback is executed when a session is to be started, a session ID is supplied
238
+
and <link linkend="ini.session.use-strict-mode">session.use_strict_mode</link> is enabled.
239
+
The <parameter>key</parameter> is the session ID to validate.
240
+
A session ID is valid, if a session with that ID already exists.
241
+
The return value should be &true; for success, &false; for failure.
242
+
</para>
243
+
</listitem>
244
+
</varlistentry>
245
+
<varlistentry>
246
+
<term><parameter>update_timestamp</parameter></term>
247
+
<listitem>
248
+
<para>
249
+
A callable with the following signature:
250
+
<methodsynopsis>
251
+
<type>bool</type><methodname><replaceable>update_timestamp</replaceable></methodname>
252
+
<methodparam><type>string</type><parameter>key</parameter></methodparam>
253
+
<methodparam><type>string</type><parameter>val</parameter></methodparam>
254
+
</methodsynopsis>
255
+
</para>
256
+
<para>
257
+
This callback is executed when a session is updated.
258
+
<parameter>key</parameter> is the session ID, <parameter>val</parameter> is the session data.
259
+
The return value should be &true; for success, &false; for failure.
260
+
</para>
261
+
</listitem>
262
+
</varlistentry>
172
263
</variablelist>
173
264
</para>
174
265
</refsect1>
...
...
@@ -185,11 +276,11 @@
185
276
<para>
186
277
<example>
187
278
<title>
188
-
Custom session handler: see full code in <classname>SessionHandlerInterface</classname> synposis.
279
+
Custom session handler: see full code in <classname>SessionHandlerInterface</classname> synopsis.
189
280
</title>
190
281
<para>
191
-
The following code is for PHP version 5.4.0 and above. We just show the invokation here, the full example can be
192
-
seen in the <classname>SessionHandlerInterface</classname> synposis linked above.
282
+
We just show the invocation here, the full example can be
283
+
seen in the <classname>SessionHandlerInterface</classname> synopsis linked above.
193
284
</para>
194
285
<para>
195
286
Note we use the OOP prototype with <function>session_set_save_handler</function> and
...
...
@@ -212,95 +303,6 @@ session_start();
212
303
]]>
213
304
</programlisting>
214
305
</example>
215
-
<example>
216
-
<title>Custom session save handler using objects</title>
217
-
<para>
218
-
The following code is for PHP versions less than 5.4.0.
219
-
</para>
220
-
<para>
221
-
The following example provides file based session storage similar to the
222
-
PHP sessions default save handler <parameter>files</parameter>. This
223
-
example could easily be extended to cover database storage using your
224
-
favorite PHP supported database engine.
225
-
</para>
226
-
<para>
227
-
Note we additionally register the shutdown function <function>session_write_close</function>
228
-
using <function>register_shutdown_function</function> under PHP less than 5.4.0.
229
-
This is generally advised when registering objects as session save handlers under PHP less
230
-
than 5.4.0.
231
-
</para>
232
-
<programlisting role="php">
233
-
<![CDATA[
234
-
<?php
235
-
class FileSessionHandler
236
-
{
237
-
private $savePath;
238
-

239
-
function open($savePath, $sessionName)
240
-
{
241
-
$this->savePath = $savePath;
242
-
if (!is_dir($this->savePath)) {
243
-
mkdir($this->savePath, 0777);
244
-
}
245
-

246
-
return true;
247
-
}
248
-

249
-
function close()
250
-
{
251
-
return true;
252
-
}
253
-

254
-
function read($id)
255
-
{
256
-
return (string)@file_get_contents("$this->savePath/sess_$id");
257
-
}
258
-

259
-
function write($id, $data)
260
-
{
261
-
return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
262
-
}
263
-

264
-
function destroy($id)
265
-
{
266
-
$file = "$this->savePath/sess_$id";
267
-
if (file_exists($file)) {
268
-
unlink($file);
269
-
}
270
-

271
-
return true;
272
-
}
273
-

274
-
function gc($maxlifetime)
275
-
{
276
-
foreach (glob("$this->savePath/sess_*") as $file) {
277
-
if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
278
-
unlink($file);
279
-
}
280
-
}
281
-

282
-
return true;
283
-
}
284
-
}
285
-

286
-
$handler = new FileSessionHandler();
287
-
session_set_save_handler(
288
-
array($handler, 'open'),
289
-
array($handler, 'close'),
290
-
array($handler, 'read'),
291
-
array($handler, 'write'),
292
-
array($handler, 'destroy'),
293
-
array($handler, 'gc')
294
-
);
295
-

296
-
// the following prevents unexpected effects when using objects as save handlers
297
-
register_shutdown_function('session_write_close');
298
-

299
-
session_start();
300
-
// proceed to set and retrieve values by key from $_SESSION
301
-
]]>
302
-
</programlisting>
303
-
</example>
304
306
</para>
305
307
</refsect1>
306
308

...
...
@@ -308,23 +310,7 @@ session_start();
308
310
&reftitle.notes;
309
311
<warning>
310
312
<para>
311
-
When using objects as session save handlers, it is important to register the
312
-
shutdown function with PHP to avoid unexpected side-effects from the way
313
-
PHP internally destroys objects on shutdown and may prevent the
314
-
<parameter>write</parameter> and <parameter>close</parameter> from being called.
315
-
Typically you should register <parameter>'session_write_close'</parameter> using the
316
-
<function>register_shutdown_function</function> function.
317
-
</para>
318
-
<para>
319
-
As of PHP 5.4.0 you can use <function>session_register_shutdown</function> or
320
-
simply use the 'register shutdown' flag when invoking
321
-
<function>session_set_save_handler</function> using the OOP method and passing an
322
-
instance that implements <classname>SessionHandlerInterface</classname>.
323
-
</para>
324
-
</warning>
325
-
<warning>
326
-
<para>
327
-
As of PHP 5.0.5 the <parameter>write</parameter> and
313
+
The <parameter>write</parameter> and
328
314
<parameter>close</parameter> handlers are called after object
329
315
destruction and therefore cannot use objects or throw exceptions.
330
316
Exceptions are not able to be caught since will not be caught nor will
...
...
@@ -346,35 +332,6 @@ session_start();
346
332
</warning>
347
333
</refsect1>
348
334

349
-
<refsect1 role="changelog">
350
-
&reftitle.changelog;
351
-
<informaltable>
352
-
<tgroup cols="2">
353
-
<thead>
354
-
<row>
355
-
<entry>&Version;</entry>
356
-
<entry>&Description;</entry>
357
-
</row>
358
-
</thead>
359
-
<tbody>
360
-
<row>
361
-
<entry>5.5.1</entry>
362
-
<entry>
363
-
Added the optional <parameter>create_sid</parameter> parameter.
364
-
</entry>
365
-
</row>
366
-
<row>
367
-
<entry>5.4.0</entry>
368
-
<entry>
369
-
Added <interfacename>SessionHandlerInterface</interfacename> for implementing session handlers and
370
-
<classname>SessionHandler</classname> to expose internal PHP session handlers.
371
-
</entry>
372
-
</row>
373
-
</tbody>
374
-
</tgroup>
375
-
</informaltable>
376
-
</refsect1>
377
-

378
335
<refsect1 role="seealso">
379
336
&reftitle.seealso;
380
337
<para>
...
...
@@ -388,7 +345,11 @@ session_start();
388
345
configuration directive.
389
346
</member>
390
347
<member>The <function>register_shutdown_function</function></member>
391
-
<member>The <function>session_register_shutdown</function> for PHP 5.4.0+</member>
348
+
<member>The <function>session_register_shutdown</function></member>
349
+
<member>
350
+
Refer to <link xlink:href="&url.session-save-handler;">save_handler.inc</link>
351
+
for a full procedural reference implementation
352
+
</member>
392
353
</simplelist>
393
354
</para>
394
355
</refsect1>
395
356



Tools (Spanish Manual)