reference/session/functions/session-set-save-handler.xml
184f3f7bd45643cb80f828d0bb001991ec3a5fad
184f3f7bd45643cb80f828d0bb001991ec3a5fad
...
...
@@ -20,19 +20,19 @@
20
20
<methodparam choice="opt"><type>callable</type><parameter>update_timestamp</parameter></methodparam>
21
21
</methodsynopsis>
22
22
<para>
23
-
Since PHP 5.4 it is possible to register the following prototype:
23
+
It is possible to register the following prototype:
24
24
</para>
25
25
<methodsynopsis>
26
26
<type>bool</type><methodname>session_set_save_handler</methodname>
27
-
<methodparam><type>SessionHandlerInterface</type><parameter>sessionhandler</parameter></methodparam>
28
-
<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>
29
29
</methodsynopsis>
30
30
<para>
31
31
<function>session_set_save_handler</function> sets the user-level
32
32
session storage functions which are used for storing and
33
33
retrieving data associated with a session. This is most useful
34
34
when a storage method other than those supplied by PHP sessions
35
-
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.
36
36
</para>
37
37
</refsect1>
38
38
...
...
@@ -46,9 +46,11 @@
46
46
<listitem>
47
47
<para>
48
48
An instance of a class implementing
49
-
<interfacename>SessionHandlerInterface</interfacename>, such as
49
+
<interfacename>SessionHandlerInterface</interfacename>, and optionally
50
+
<interfacename>SessionIdInterface</interfacename> and/or
51
+
<interfacename>SessionUpdateTimestampHandlerInterface</interfacename>, such as
50
52
<classname>SessionHandler</classname>, to register as the session
51
-
handler. Since PHP 5.4 only.
53
+
handler.
52
54
</para>
53
55
</listitem>
54
56
</varlistentry>
...
...
@@ -67,9 +69,17 @@
67
69
68
70
<variablelist>
69
71
<varlistentry>
70
-
<term><parameter>open(string $savePath, string $sessionName)</parameter></term>
72
+
<term><parameter>open</parameter></term>
71
73
<listitem>
72
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>
73
83
The open callback works like a constructor in classes and is
74
84
executed when the session is being opened. It is the first callback
75
85
function executed when the session is started automatically or
...
...
@@ -79,9 +89,16 @@
79
89
</listitem>
80
90
</varlistentry>
81
91
<varlistentry>
82
-
<term><parameter>close()</parameter></term>
92
+
<term><parameter>close</parameter></term>
83
93
<listitem>
84
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>
85
102
The close callback works like a destructor in classes and is
86
103
executed after the session write callback has been called. It is also invoked when
87
104
<function>session_write_close</function> is called.
...
...
@@ -90,9 +107,16 @@
90
107
</listitem>
91
108
</varlistentry>
92
109
<varlistentry>
93
-
<term><parameter>read(string $sessionId)</parameter></term>
110
+
<term><parameter>read</parameter></term>
94
111
<listitem>
95
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>
96
120
The <parameter>read</parameter> callback must always return a session encoded (serialized)
97
121
string, or an empty string if there is no data to read.
98
122
</para>
...
...
@@ -106,14 +130,22 @@
106
130
passed for storage to the <parameter>write</parameter> callback. The value returned will be
107
131
unserialized automatically by PHP and used to populate the <varname>$_SESSION</varname> superglobal.
108
132
While the data looks similar to <function>serialize</function> please note it is a different format
109
-
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.
110
134
</para>
111
135
</listitem>
112
136
</varlistentry>
113
137
<varlistentry>
114
-
<term><parameter>write(string $sessionId, string $data)</parameter></term>
138
+
<term><parameter>write</parameter></term>
115
139
<listitem>
116
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>
117
149
The <parameter>write</parameter> callback is called when the session needs to be saved and closed. This
118
150
callback receives the current session ID a serialized version the <varname>$_SESSION</varname> superglobal. The serialization
119
151
method used internally by PHP is specified in the <link linkend="ini.session.serialize-handler">session.serialize_handler</link> ini setting.
...
...
@@ -139,9 +171,16 @@
139
171
</listitem>
140
172
</varlistentry>
141
173
<varlistentry>
142
-
<term><parameter>destroy($sessionId)</parameter></term>
174
+
<term><parameter>destroy</parameter></term>
143
175
<listitem>
144
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>
145
184
This callback is executed when a session is destroyed with <function>session_destroy</function> or with
146
185
<function>session_regenerate_id</function> with the destroy parameter set to &true;.
147
186
Return value should be &true; for success, &false; for failure.
...
...
@@ -149,9 +188,16 @@
149
188
</listitem>
150
189
</varlistentry>
151
190
<varlistentry>
152
-
<term><parameter>gc($lifetime)</parameter></term>
191
+
<term><parameter>gc</parameter></term>
153
192
<listitem>
154
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>
155
201
The garbage collector callback is invoked internally by PHP periodically in order to
156
202
purge old session data. The frequency is controlled by
157
203
<link linkend="ini.session.gc-probability">session.gc_probability</link> and <link linkend="ini.session.gc-divisor">session.gc_divisor</link>.
...
...
@@ -161,15 +207,59 @@
161
207
</listitem>
162
208
</varlistentry>
163
209
<varlistentry>
164
-
<term><parameter>create_sid()</parameter></term>
210
+
<term><parameter>create_sid</parameter></term>
165
211
<listitem>
166
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>
167
220
This callback is executed when a new session ID is required. No
168
221
parameters are provided, and the return value should be a string that
169
222
is a valid session ID for your handler.
170
223
</para>
171
224
</listitem>
172
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>
173
263
</variablelist>
174
264
</para>
175
265
</refsect1>
...
...
@@ -186,11 +276,11 @@
186
276
<para>
187
277
<example>
188
278
<title>
189
-
Custom session handler: see full code in <classname>SessionHandlerInterface</classname> synposis.
279
+
Custom session handler: see full code in <classname>SessionHandlerInterface</classname> synopsis.
190
280
</title>
191
281
<para>
192
-
The following code is for PHP version 5.4.0 and above. We just show the invokation here, the full example can be
193
-
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.
194
284
</para>
195
285
<para>
196
286
Note we use the OOP prototype with <function>session_set_save_handler</function> and
...
...
@@ -213,95 +303,6 @@ session_start();
213
303
]]>
214
304
</programlisting>
215
305
</example>
216
-
<example>
217
-
<title>Custom session save handler using objects</title>
218
-
<para>
219
-
The following code is for PHP versions less than 5.4.0.
220
-
</para>
221
-
<para>
222
-
The following example provides file based session storage similar to the
223
-
PHP sessions default save handler <parameter>files</parameter>. This
224
-
example could easily be extended to cover database storage using your
225
-
favorite PHP supported database engine.
226
-
</para>
227
-
<para>
228
-
Note we additionally register the shutdown function <function>session_write_close</function>
229
-
using <function>register_shutdown_function</function> under PHP less than 5.4.0.
230
-
This is generally advised when registering objects as session save handlers under PHP less
231
-
than 5.4.0.
232
-
</para>
233
-
<programlisting role="php">
234
-
<![CDATA[
235
-
<?php
236
-
class FileSessionHandler
237
-
{
238
-
private $savePath;
239
-
240
-
function open($savePath, $sessionName)
241
-
{
242
-
$this->savePath = $savePath;
243
-
if (!is_dir($this->savePath)) {
244
-
mkdir($this->savePath, 0777);
245
-
}
246
-
247
-
return true;
248
-
}
249
-
250
-
function close()
251
-
{
252
-
return true;
253
-
}
254
-
255
-
function read($id)
256
-
{
257
-
return (string)@file_get_contents("$this->savePath/sess_$id");
258
-
}
259
-
260
-
function write($id, $data)
261
-
{
262
-
return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
263
-
}
264
-
265
-
function destroy($id)
266
-
{
267
-
$file = "$this->savePath/sess_$id";
268
-
if (file_exists($file)) {
269
-
unlink($file);
270
-
}
271
-
272
-
return true;
273
-
}
274
-
275
-
function gc($maxlifetime)
276
-
{
277
-
foreach (glob("$this->savePath/sess_*") as $file) {
278
-
if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
279
-
unlink($file);
280
-
}
281
-
}
282
-
283
-
return true;
284
-
}
285
-
}
286
-
287
-
$handler = new FileSessionHandler();
288
-
session_set_save_handler(
289
-
array($handler, 'open'),
290
-
array($handler, 'close'),
291
-
array($handler, 'read'),
292
-
array($handler, 'write'),
293
-
array($handler, 'destroy'),
294
-
array($handler, 'gc')
295
-
);
296
-
297
-
// the following prevents unexpected effects when using objects as save handlers
298
-
register_shutdown_function('session_write_close');
299
-
300
-
session_start();
301
-
// proceed to set and retrieve values by key from $_SESSION
302
-
]]>
303
-
</programlisting>
304
-
</example>
305
306
</para>
306
307
</refsect1>
307
308
...
...
@@ -309,23 +310,7 @@ session_start();
309
310
&reftitle.notes;
310
311
<warning>
311
312
<para>
312
-
When using objects as session save handlers, it is important to register the
313
-
shutdown function with PHP to avoid unexpected side-effects from the way
314
-
PHP internally destroys objects on shutdown and may prevent the
315
-
<parameter>write</parameter> and <parameter>close</parameter> from being called.
316
-
Typically you should register <parameter>'session_write_close'</parameter> using the
317
-
<function>register_shutdown_function</function> function.
318
-
</para>
319
-
<para>
320
-
As of PHP 5.4.0 you can use <function>session_register_shutdown</function> or
321
-
simply use the 'register shutdown' flag when invoking
322
-
<function>session_set_save_handler</function> using the OOP method and passing an
323
-
instance that implements <classname>SessionHandlerInterface</classname>.
324
-
</para>
325
-
</warning>
326
-
<warning>
327
-
<para>
328
-
As of PHP 5.0.5 the <parameter>write</parameter> and
313
+
The <parameter>write</parameter> and
329
314
<parameter>close</parameter> handlers are called after object
330
315
destruction and therefore cannot use objects or throw exceptions.
331
316
Exceptions are not able to be caught since will not be caught nor will
...
...
@@ -347,35 +332,6 @@ session_start();
347
332
</warning>
348
333
</refsect1>
349
334
350
-
<refsect1 role="changelog">
351
-
&reftitle.changelog;
352
-
<informaltable>
353
-
<tgroup cols="2">
354
-
<thead>
355
-
<row>
356
-
<entry>&Version;</entry>
357
-
<entry>&Description;</entry>
358
-
</row>
359
-
</thead>
360
-
<tbody>
361
-
<row>
362
-
<entry>5.5.1</entry>
363
-
<entry>
364
-
Added the optional <parameter>create_sid</parameter> parameter.
365
-
</entry>
366
-
</row>
367
-
<row>
368
-
<entry>5.4.0</entry>
369
-
<entry>
370
-
Added <interfacename>SessionHandlerInterface</interfacename> for implementing session handlers and
371
-
<classname>SessionHandler</classname> to expose internal PHP session handlers.
372
-
</entry>
373
-
</row>
374
-
</tbody>
375
-
</tgroup>
376
-
</informaltable>
377
-
</refsect1>
378
-
379
335
<refsect1 role="seealso">
380
336
&reftitle.seealso;
381
337
<para>
...
...
@@ -389,7 +345,7 @@ session_start();
389
345
configuration directive.
390
346
</member>
391
347
<member>The <function>register_shutdown_function</function></member>
392
-
<member>The <function>session_register_shutdown</function> for PHP 5.4.0+</member>
348
+
<member>The <function>session_register_shutdown</function></member>
393
349
<member>
394
350
Refer to <link xlink:href="&url.session-save-handler;">save_handler.inc</link>
395
351
for a full procedural reference implementation
396
352