Setzt benutzerdefinierte Session-Speicherfunktionen

# session_set_save_handler

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

session_set_save_handler — Setzt benutzerdefinierte Session-Speicherfunktionen

### Beschreibung

function 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:

function 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:

  function 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:

  function 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:

  function 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:

  function 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:

  function 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:

  function 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:

  function 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:

  function 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:

  function 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

- 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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open