(PHP 4, PHP 5, PHP 7, PHP 8)
session_set_save_handler — Setzt benutzerdefinierte Session-Speicherfunktionen
$open
,$close
,$read
,$write
,$destroy
,$gc
,$create_sid
= ?,$validate_sid
= ?,$update_timestamp
= ?Folgenden Prototypen können registriert werden:
session_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.
sessionhandler
Eine Instanz einer Klasse, die SessionHandlerInterface, und optional SessionIdInterface und/oder SessionUpdateTimestampHandlerInterface implementiert, wie beispielsweise SessionHandler, die als benutzerdefinierte Session-Speicherroutine registriert werden soll.
register_shutdown
Registriert session_write_close() als eine register_shutdown_function()-Funktion.
open
Ein Callable mit folgender Signatur:
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 bei Erfolg true
und im Fall eines Fehlers false
.
close
Ein 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 bei Erfolg true
sein und im Fall eines Fehlers false
.
read
Ein Callable mit folgender Signatur:
Der 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 ini-Einstellung session.serialize_handler beschrieben wird.
write
Ein Callable mit folgender Signatur:
Der write
-Callback wird aufgerufen, wenn die Session gespeichert und geschlossen werden muss. Dieser Callback nimmt die aktuelle Session-ID und eine serialisierte Version der superglobalen $_SESSION-Variablen entgegen. Die intern von PHP verwendete Serialisierungsmethode wird in der Dokumentation zur ini-Einstellung session.serialize_handler beschrieben.
Die serialisierten Session-Daten, die an diesen Callback übergeben werden, sollten als zu der übergebenen Session-ID 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 "write"-Routine wird nicht ausgeführt, bevor die Ausgabe abgeschlossen ist. Deshalb werden auch niemals Fehlermeldungen der "write"-Routine im Browser erscheinen. Wenn die Ausgabe von Fehlermeldungen nötig ist, sollte diese stattdessen in eine Datei geschrieben werden.
destroy
Ein Callable mit folgender Signatur:
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 bei Erfolg true
sein und im Fall eines Fehlers false
.
gc
Ein Callable mit folgender Signatur:
Der Garbage-Collection-Callback wird von PHP intern aufgerufen, um alte Session-Daten 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 bei Erfolg true
sein und im Fall eines Fehlers false
.
create_sid
Ein 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 die Routine darstellt.
validate_sid
Ein Callable mit folgender Signatur:
Dieser Callback wird ausgeführt, wenn eine Session gestartet werden soll, eine Session-ID bereitgestellt wurde und session.use_strict_mode aktiv ist. 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 bei Erfolg true
sein und im Fall eines Fehlers false
.
update_timestamp
Ein Callable mit folgender Signatur:
Dieser Callback wird ausgeführt, wenn eine Session aktualisiert wird. key
ist die Session-ID, val
sind die Session-Daten. Der Rückgabewert sollte bei Erfolg true
sein und im Fall eines Fehlers false
.
Beispiel #1 Benutzerdefierte Session-Routine; der vollständige Code ist bei SessionHandlerInterface aufgeführt
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-Speicherroutinen 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
Die Routinen write
und close
werden 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.