session_set_save_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

session_set_save_handler — Setzt benutzerdefinierte Session-Speicherfunktionen

Beschreibung

session_set_save_handler(
    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:

session_set_save_handler(object $sessionhandler, bool $register_shutdown = true): bool

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.

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.

oder
open

Ein Callable mit folgender Signatur:

open(string $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 bei Erfolg true und im Fall eines Fehlers false.

close

Ein Callable mit folgender Signatur:

close(): bool

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:

read(string $sessionId): string

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:

write(string $sessionId, string $data): bool

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:

destroy(string $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 bei Erfolg true sein und im Fall eines Fehlers false.

gc

Ein Callable mit folgender Signatur:

gc(int $lifetime): bool

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:

create_sid(): string

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:

validate_sid(string $key): bool

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:

update_timestamp(string $key, string $val): bool

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.

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

Warnung

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.

Warnung

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