session_set_save_handler
(PHP 4, PHP 5, PHP 7, PHP 8)
session_set_save_handler — Setzt benutzerdefinierte Session-Speicherfunktionen
Beschreibung
callable
$open,callable
$close,callable
$read,callable
$write,callable
$destroy,callable
$gc,callable
$create_sid = ?,callable
$validate_sid = ?,callable
$update_timestamp = ?): bool
Folgenden Prototypen können registriert werden:
$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.
Parameter-Liste
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:
open(string$savePath, string$sessionName): boolDer 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
trueund im Fall eines Fehlersfalse. -
close -
Ein Callable mit folgender Signatur:
close(): boolDer 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
truesein und im Fall eines Fehlersfalse. -
read -
Ein Callable mit folgender Signatur:
read(string$sessionId): stringDer
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:
write(string$sessionId, string$data): boolDer
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 denwrite-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:
destroy(string$sessionId): boolDieser Callback wird ausgeführt, wenn eine Session duch session_destroy() oder session_regenerate_id(), mit dem $destroy-Parameter auf
truegesetzt, zerstört wird. Der Rückgabewert sollte bei Erfolgtruesein und im Fall eines Fehlersfalse. -
gc -
Ein Callable mit folgender Signatur:
gc(int$lifetime): boolDer 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
truesein und im Fall eines Fehlersfalse. -
create_sid -
Ein Callable mit folgender Signatur:
create_sid(): stringDieser 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:
validate_sid(string$key): boolDieser Callback wird ausgeführt, wenn eine Session gestartet werden soll, eine Session-ID bereitgestellt wurde und session.use_strict_mode aktiv ist.
keyist die zu validierende Session-ID. Eine Session-ID is gültig, wenn eine Session mit dieser ID bereits existiert. Der Rückgabewert sollte bei Erfolgtruesein und im Fall eines Fehlersfalse. -
update_timestamp -
Ein Callable mit folgender Signatur:
update_timestamp(string$key, string$val): boolDieser Callback wird ausgeführt, wenn eine Session aktualisiert wird.
keyist die Session-ID,valsind die Session-Daten. Der Rückgabewert sollte bei Erfolgtruesein und im Fall eines Fehlersfalse.
Rückgabewerte
Gibt bei Erfolg true zurück. Bei einem Fehler wird false zurückgegeben.
Beispiele
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
Anmerkungen
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.
Siehe auch
- Die Konfigurationsanweisung session.save_handler
- Die Konfigurationsanweisung session.serialize_handler
- register_shutdown_function() - Registriert eine Funktion zur Ausführung beim Skript-Abschluss
- session_register_shutdown() - Funktion zum Schließen von Sessions
- Eine vollständige prozedurale Referenzimplementierung kann » save_handler.inc entnommen werden
