session_set_save_handler

(PHP 4, PHP 5, PHP 7)

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

Seit PHP 5.4 ist es möglich folgenden Prototypen zu registrieren:

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

Ein Exemplar einer Klasse, die SessionHandlerInterface, SessionIdInterface und/oder SessionUpdateTimestampHandlerInterface implementiert, wie beispielsweise SessionHandler, das als benutzerdefinierte Session-Speicherfunktion registriert werden soll. Erst seit PHP 5.4.

register_shutdown

Registriert session_write_close() als eine register_shutdown_function() Funktion.

oder
open(string $savePath, string $sessionName)

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.

close()

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.

read(string $sessionId)

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.

write(string $sessionId, string $data)

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.

destroy($sessionId)

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.

gc($lifetime)

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_sid()

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.

Rückgabewerte

Gibt bei Erfolg TRUE zurück. Im Fehlerfall wird FALSE zurückgegeben.

Changelog

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.

Beispiele

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

Anmerkungen

Warnung

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.

Warnung

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.

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