(PHP 4, PHP 5, PHP 7)
session_set_save_handler — Setzt benutzerdefinierte Session-Speicherfunktionen
$open
, callable $close
, callable $read
, callable $write
, callable $destroy
, callable $gc
[, callable $create_sid
[, callable $validate_sid
[, callable $update_timestamp
]]] ) : boolSeit PHP 5.4 ist es möglich folgenden Prototypen zu registrieren:
$sessionhandler
[, bool $register_shutdown = TRUE
] ) : boolsession_set_save_handler() setzt die benutzerdefinierten Session-Speicherfunktionen, die zur Speicherung und Wiederherstellung von zur Session gehörigen Daten verwendet werden. Dies ist äußerst nützlich, wenn eine andere als die mit PHP-Sessions zur Verfügung stehende Art der Speicherung, z.B. die Speicherung der Session-Daten in einer lokalen Datenbank, bevorzugt wird.
Diese Funktion hat zwei Prototypen.
sessionhandlerEin Exemplar einer Klasse, die SessionHandlerInterface, und optional SessionIdInterface und/oder SessionUpdateTimestampHandlerInterface implementiert, wie beispielsweise SessionHandler, das als benutzerdefinierte Session-Speicherfunktion registriert werden soll. Erst seit PHP 5.4.
register_shutdownRegistriert session_write_close() als eine register_shutdown_function() Funktion.
openEin Callable mit folgender Signatur:
$savePath
, string $sessionName
) : bool
Der open Callback funktionert wie ein Konstruktor in einer Klasse und
wird ausgeführt, wenn die Session geöffnet wird. Es ist die erste
Callback-Funktion, die ausgeführt wird, wenn die Session automatisch oder
manuell durch session_start() gestartet wird. Der
Rückgabewert ist TRUE im Erfolgs-, und FALSE im Fehlerfall.
closeEin Callable mit folgender Signatur:
Der close Callback funktionert wie ein Destruktor in einer Klasse
und wird ausgeführt nachdem der Session write Callback aufgerufen wurde.
Sie wird ebenfalls aufgerufen, wenn
session_write_close() aufgerufen wurde. Der
Rückgabewert sollte TRUE im Erfolgs- und FALSE im Fehlerfall sein.
readEin Callable mit folgender Signatur:
$sessionId
) : bool
Die read Callback muss immer eine sitzungskodierte
(serialisierte) Zeichenkette zurückgeben, oder eine leere Zeichenkette,
falls keine Daten zu lesen sind.
Dieser Callback wird intern von PHP aufgerufen, wenn die Session
startet, oder wenn session_start() aufgerufen wird.
Noch bevor dieser Callback aufgerufen wird, wird PHP den
open Callback ausführen.
Der Wert, den dieser Callback zurückgibt, muss in genau demselben
serialisierten Format vorliegen, das ursprünglich für die Speicherung an
den write Callback übergeben wurde. Der
zurückgegebene Wert wird von PHP automatisch deserialisiert, und
verwendet, um die superglobale $_SESSION Variable zu initialisieren.
Obgleich die Daten ähnlich wie bei serialize()
aussehen, ist zu beachten, dass es sich um ein unterschiedliches Format
handelt, das in der Dokumentation zur session.serialize_handler
ini Einstellung beschrieben wird.
writeEin Callable mit folgender Signatur:
$sessionId
, string $data
) : bool
Der write Callback wird aufgerufen, wenn die
Session gespeichert und geschlossen werden muss. Dieser Callback nimmt
die aktuelle Sessionkennung und eine serialisierte Version der
superglobalen $_SESSION Variablen entgegen. Die intern von PHP verwendete
Serialisierungsmethode wird in der Dokumentation zur session.serialize_handler
ini Einstellung beschrieben.
Die serialisierten Sessiondaten, die an diesen Callback übergeben werden,
sollten als zu der übergebenen Sessionkennung zugehörig gespeichert
werden. Werden diese Daten wieder gelesen, dann muss der
read Callback den genauen Wert liefern, der
ursprünglich an den write Callback übergeben
wurde.
Dieser Callback wird aufgerufen, wenn PHP herunterfährt, oder explizit,
wenn session_write_close() aufgerufen wird. Es ist zu
beachten, dass PHP intern nach Ausführung dieser Funktion den
close Callback ausführen wird.
Hinweis:
Die schreiben-Routine wird nicht ausgeführt, bevor die Ausgabe abgeschlossen ist. Deshalb werden auch niemals Fehlermeldungen der schreiben-Routine im Browser erscheinen. Wenn die Ausgabe von Fehlermeldungen nötig ist, sollte diese stattdessen in eine Datei geschrieben werden.
destroyEin Callable mit folgender Signatur:
$sessionId
) : bool
Dieser Callback wird ausgeführt, wenn eine Session duch
session_destroy() oder
session_regenerate_id(), mit dem $destroy Parameter
auf TRUE gesetzt, zerstört wird.
Der Rückgabewert sollte TRUE im Erfolgs und FALSE im Fehlerfall sein.
gcEin Callable mit folgender Signatur:
$lifetime
) : bool
Der Garbage Collection Callback wird von PHP intern aufgerufen, um alte
Sessiondaten zu löschen. Die Häufigkeit wird durch session.gc_probability
und session.gc_divisor
gesteuert. Der Wert der Lebensdauer, die diesem Callback übergeben wird,
kann mit session.gc_maxlifetime
festgelegt werden. Der Rückgabewert sollte TRUE im Erfolgs- und FALSE
im Fehlerfall sein.
create_sidEin Callable mit folgender Signatur:
Dieser Callback wird ausgeführt, wenn eine neue Session-ID benötigt wird. Es werden keine Parameter übergeben, und der Rückgabewert sollte eine Zeichenkette sein, die eine gültige Session-ID für den Handler darstellt.
validate_sidEin Callable mit folgender Signatur:
$key
) : bool
Dieser Callback wird ausgeführt, gerade bevor eine Session gestartet werden soll,
eine Session-ID bereitgestellt wurde, und session.use_strict_mode
aktiv ist. Der key ist die zu validierende Session-ID.
Eine Session-ID is gültig, wenn eine Session mit dieser ID bereits existiert.
Der Rückgabewert sollte TRUE bei Erfolg und FALSE im Fehlerfall sein.
update_timestampEin Callable mit folgender Signatur:
$key
, string $val
) : string
Dieser Callback wird ausgeführt, wenn eine Session aktualisiert wird.
key ist die Session-ID, val sind die Session-Daten.
Der Rückgabewert sollte TRUE bei Erfolg und FALSE im Fehlerfall sein.
Gibt bei Erfolg TRUE zurück. Im Fehlerfall wird FALSE zurückgegeben.
| Version | Beschreibung |
|---|---|
| 7.0.0 |
Die optionalen Parameter validate_sid und
update_timestamp wurden hinzugefügt.
|
| 5.5.1 |
Der optionale Parameter create_sid wurde hinzugefügt.
|
| 5.4.0 | SessionHandlerInterface zum Implementieren von Session-Handlern und SessionHandler, um interne PHP Session-Handler bereitzustellen, hinzugefügt. |
Beispiel #1 Benutzerdefierter Session-Handler; der vollständige Code ist bei SessionHandlerInterface aufgeführt
Der folgende Code ist für PHP-Version 5.4.0 und höher. Hier wird nur der Aufruf gezeigt; der vollständige Beispielcode ist in der Dokumentation von SessionHandlerInterface zu finden.
Es ist zu beachten, dass der OOP-Prototyp mit session_set_save_handler() verwendet wird, und dass die Shutdown-Funktion unter Verwendung des Parameters flag der Funktion registriert wird. Dies wird grundsätzlich empfohlen, wenn Objekte als Session-Save-Handler registriert werden.
<?php
class MySessionHandler implements SessionHandlerInterface
{
// hier wird das Interface implementiert
}
$handler = new MySessionHandler();
session_set_save_handler($handler, true);
session_start();
// fahre fort und setze und hole Werte per Schlüssel von $_SESSION
Beispiel #2 Benutzerdefinierter Session-Save-Handler, der Objekte verwendet
Der folgende Code ist für PHP-Versionen kleiner als 5.4.0.
Das folgende Beispiel liefert eine dateibasierte Session-Speicherung, die
der Standard-Speicherroutine files der
PHP-Sessions ähnlich ist. Dieses Beispiel kann problemlos erweitert
werden, dass es Datenbank-Speicherung mittels ihrer bevorzugten
PHP-gestützten Datenbank beinhaltet.
Es ist zu beachten, dass zusätzlich die Shutdown-Funktion session_write_close() unter Verwendung von register_shutdown_function() unter PHP kleiner 5.4.0 registriert wird. Dies wird grundsätzlich empfohlen, wenn Objekte als Session-Save-Handler unter PHP kleiner 5.4.0 registriert werden.
class FileSessionHandler
{
private $savePath;
function open($savePath, $sessionName)
{
$this->savePath = $savePath;
if (!is_dir($this->savePath)) {
mkdir($this->savePath, 0777);
}
return true;
}
function close()
{
return true;
}
function read($id)
{
return (string)@file_get_contents("$this->savePath/sess_$id");
}
function write($id, $data)
{
return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
}
function destroy($id)
{
$file = "$this->savePath/sess_$id";
if (file_exists($file)) {
unlink($file);
}
return true;
}
function gc($maxlifetime)
{
foreach (glob("$this->savePath/sess_*") as $file) {
if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
unlink($file);
}
}
return true;
}
}
$handler = new FileSessionHandler();
session_set_save_handler(
array($handler, 'open'),
array($handler, 'close'),
array($handler, 'read'),
array($handler, 'write'),
array($handler, 'destroy'),
array($handler, 'gc')
);
// das folgende verhindert unerwartete Effekte, wenn Objekte als Save-Handler verwendet werden
register_shutdown_function('session_write_close');
session_start();
// fahre fort Werte per Schlüssel in $_SESSION zu setzen und zu holen
Werden Objekte als Session-Save-Handler verwendet, ist es wichtig die
Shutdown-Funktion mit PHP zu registrieren, um unerwartete Nebenwirkungen in
Verbindung mit der Art wie PHP intern Objekte beim Herunterfahren zerstört
zu verhindern, was dazu führen kann, dass write und
close nicht aufgerufen werden. Üblicherweise sollte
'session_write_close' unter Verwendung von
register_shutdown_function() registriert werden.
Von PHP 5.4.0 an kann session_register_shutdown() verwendet werden, oder einfach das 'register shutdown' Flag gesetzt werden, wenn session_set_save_handler() unter Verwendung der OOP-Methode und der Übergabe eines Exemplars, das SessionHandlerInterface implementiert, aufgerufen wird.
Ab PHP 5.0.5 werden die Routinen write und
close nach dem Zerstören von Objekten
aufgerufen und können deshalb keine Objekte verwenden oder Exceptions
(Fehler-, Ausnahmesituationen) auslösen. Exceptions können nicht abgefangen
werden, und es wird auch kein Exception-Trace angezeigt; die Ausführung wird
einfach unerwartet abgebrochen. Objekt-Destruktoren können
aber Sessions verwenden.
Es ist möglich, session_write_close() über den Destruktor aufzurufen, um dieses Henne-Ei Problem zu lösen, aber der verlässlichste Weg ist das Registrieren einer Shutdown-Funktion wie oben beschrieben.
Bei manchen SAPIs ändert sich das aktuelle Arbeitsverzeichnis, falls die Session durch die Beendigung des Skripts geschlossen wird. Mittels session_write_close() ist es möglich, die Session schon früher zu schließen.