session-set-save-handler.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 184f3f7bd45643cb80f828d0bb001991ec3a5fad Maintainer: samesch Status: ready -->
<!-- Reviewed: yes Maintainer: samesch -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.session-set-save-handler" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>session_set_save_handler</refname>
  <refpurpose>Setzt benutzerdefinierte Session-Speicherfunktionen</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>callable</type><parameter>open</parameter></methodparam>
   <methodparam><type>callable</type><parameter>close</parameter></methodparam>
   <methodparam><type>callable</type><parameter>read</parameter></methodparam>
   <methodparam><type>callable</type><parameter>write</parameter></methodparam>
   <methodparam><type>callable</type><parameter>destroy</parameter></methodparam>
   <methodparam><type>callable</type><parameter>gc</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>create_sid</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>validate_sid</parameter></methodparam>
   <methodparam choice="opt"><type>callable</type><parameter>update_timestamp</parameter></methodparam>
  </methodsynopsis>
  <para>
   Folgenden Prototypen können registriert werden:
  </para>
  <methodsynopsis>
   <type>bool</type><methodname>session_set_save_handler</methodname>
   <methodparam><type>object</type><parameter>sessionhandler</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>register_shutdown</parameter><initializer>&true;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>session_set_save_handler</function> 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, &zb; die Speicherung der Session-Daten in einer lokalen
   Datenbank, bevorzugt wird.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   Diese Funktion hat zwei Prototypen.
   <variablelist>
    <varlistentry>
     <term><parameter>sessionhandler</parameter></term>
     <listitem>
      <para>
       Eine Instanz einer Klasse, die
       <interfacename>SessionHandlerInterface</interfacename>, und optional
       <interfacename>SessionIdInterface</interfacename> und/oder
       <interfacename>SessionUpdateTimestampHandlerInterface</interfacename>
       implementiert, wie beispielsweise
       <classname>SessionHandler</classname>, die als benutzerdefinierte
       Session-Speicherroutine registriert werden soll.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>register_shutdown</parameter></term>
     <listitem>
      <para>
       Registriert <function>session_write_close</function> als eine
       <function>register_shutdown_function</function>-Funktion.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>

   oder

   <variablelist>
    <varlistentry>
     <term><parameter>open</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>open</replaceable></methodname>
        <methodparam><type>string</type><parameter>savePath</parameter></methodparam>
        <methodparam><type>string</type><parameter>sessionName</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       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 <function>session_start</function> gestartet wird.
       Der Rückgabewert ist bei Erfolg &true; und im Fall eines Fehlers
       &false;.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>close</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>close</replaceable></methodname>
        <void/>
       </methodsynopsis>
      </para>
      <para>
       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
       <function>session_write_close</function> aufgerufen wurde. Der
       Rückgabewert sollte bei Erfolg &true; sein und im Fall eines Fehlers
       &false;.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>read</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>string</type><methodname><replaceable>read</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Der <parameter>read</parameter>-Callback muss immer eine
       sitzungskodierte (serialisierte) Zeichenkette zurückgeben, oder eine
       leere Zeichenkette, falls keine Daten zu lesen sind.
      </para>
      <para>
       Dieser Callback wird intern von PHP aufgerufen, wenn die Session
       startet, oder wenn <function>session_start</function> aufgerufen wird.
       Noch bevor dieser Callback aufgerufen wird, wird PHP den
       <parameter>open</parameter>-Callback ausführen.
      </para>
      <para>
       Der Wert, den dieser Callback zurückgibt, muss in genau demselben
       serialisierten Format vorliegen, das ursprünglich für die Speicherung
       an den <parameter>write</parameter>-Callback übergeben wurde. Der
       zurückgegebene Wert wird von PHP automatisch deserialisiert, und
       verwendet, um die superglobale <varname>$_SESSION</varname>-Variable zu
       initialisieren. Obgleich die Daten ähnlich wie bei
       <function>serialize</function> aussehen, ist zu beachten, dass es sich
       um ein unterschiedliches Format handelt, das in der Dokumentation zur
       ini-Einstellung
       <link linkend="ini.session.serialize-handler">session.serialize_handler</link>
       beschrieben wird.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>write</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>write</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
        <methodparam><type>string</type><parameter>data</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Der <parameter>write</parameter>-Callback wird aufgerufen, wenn die
       Session gespeichert und geschlossen werden muss. Dieser Callback nimmt
       die aktuelle Session-ID und eine serialisierte Version der
       superglobalen <varname>$_SESSION</varname>-Variablen entgegen. Die
       intern von PHP verwendete Serialisierungsmethode wird in der
       Dokumentation zur ini-Einstellung
       <link linkend="ini.session.serialize-handler">session.serialize_handler</link>
       beschrieben.
      </para>
      <para>
       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
       <parameter>read</parameter>-Callback den genauen Wert liefern, der
       ursprünglich an den <parameter>write</parameter>-Callback übergeben
       wurde.
      </para>
      <para>
       Dieser Callback wird aufgerufen, wenn PHP herunterfährt, oder explizit,
       wenn <function>session_write_close</function> aufgerufen wird. Es ist
       zu beachten, dass PHP intern nach Ausführung dieser Funktion den
       <parameter>close</parameter>-Callback ausführen wird.
       <note>
        <para>
         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.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>destroy</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>destroy</replaceable></methodname>
        <methodparam><type>string</type><parameter>sessionId</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Dieser Callback wird ausgeführt, wenn eine Session duch
       <function>session_destroy</function> oder
       <function>session_regenerate_id</function>, mit dem $destroy-Parameter
       auf &true; gesetzt, zerstört wird. Der Rückgabewert sollte bei Erfolg
       &true; sein und im Fall eines Fehlers &false;.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>gc</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>gc</replaceable></methodname>
        <methodparam><type>int</type><parameter>lifetime</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Der Garbage-Collection-Callback wird von PHP intern aufgerufen, um alte
       Session-Daten zu löschen. Die Häufigkeit wird durch
       <link linkend="ini.session.gc-probability">session.gc_probability</link>
       und
       <link linkend="ini.session.gc-divisor">session.gc_divisor</link>
       gesteuert. Der Wert der Lebensdauer, die diesem Callback übergeben
       wird, kann mit
       <link linkend="ini.session.gc-maxlifetime">session.gc_maxlifetime</link>
       festgelegt werden. Der Rückgabewert sollte bei Erfolg &true; sein und
       im Fall eines Fehlers &false;.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>create_sid</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>string</type><methodname><replaceable>create_sid</replaceable></methodname>
        <void/>
       </methodsynopsis>
      </para>
      <para>
       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.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>validate_sid</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>validate_sid</replaceable></methodname>
        <methodparam><type>string</type><parameter>key</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Dieser Callback wird ausgeführt, wenn eine Session gestartet
       werden soll, eine Session-ID bereitgestellt wurde und
       <link linkend="ini.session.use-strict-mode">session.use_strict_mode</link>
       aktiv ist. <parameter>key</parameter> 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;.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>update_timestamp</parameter></term>
     <listitem>
      <para>
       Ein Callable mit folgender Signatur:
       <methodsynopsis>
        <type>bool</type><methodname><replaceable>update_timestamp</replaceable></methodname>
        <methodparam><type>string</type><parameter>key</parameter></methodparam>
        <methodparam><type>string</type><parameter>val</parameter></methodparam>
       </methodsynopsis>
      </para>
      <para>
       Dieser Callback wird ausgeführt, wenn eine Session aktualisiert wird.
       <parameter>key</parameter> ist die Session-ID,
       <parameter>val</parameter> sind die Session-Daten. Der Rückgabewert
       sollte bei Erfolg &true; sein und im Fall eines Fehlers &false;.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>
     Benutzerdefierte Session-Routine; der vollständige Code ist bei
     <classname>SessionHandlerInterface</classname> aufgeführt
    </title>
    <para>
     Hier wird nur der Aufruf gezeigt; der vollständige Beispielcode ist in
     der Dokumentation von <classname>SessionHandlerInterface</classname> zu
     finden.
    </para>
    <para>
     Es ist zu beachten, dass der OOP-Prototyp mit
     <function>session_set_save_handler</function> 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.
    </para>
    <programlisting role="php">
<![CDATA[
<?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
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    Die Routinen <parameter>write</parameter> und <parameter>close</parameter>
    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.
   </para>
   <para>
    Es ist möglich, <function>session_write_close</function> ü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.
   </para>
  </warning>
  <warning>
   <para>
    Bei manchen SAPIs ändert sich das aktuelle Arbeitsverzeichnis, falls die
    Session durch die Beendigung des Skripts geschlossen wird. Mittels
    <function>session_write_close</function> ist es möglich, die Session schon
    früher zu schließen.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member>
     Die Konfigurationsanweisung
     <link linkend="ini.session.save-handler">session.save_handler</link>
    </member>
    <member>
     Die Konfigurationsanweisung
     <link linkend="ini.session.serialize-handler">session.serialize_handler</link>
    </member>
    <member><function>register_shutdown_function</function></member>
    <member><function>session_register_shutdown</function></member>
    <member>
     Eine vollständige prozedurale Referenzimplementierung kann
     <link xlink:href="&url.session-save-handler;">save_handler.inc</link>
     entnommen werden
    </member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->