<?xml version="1.0" encoding="iso-8859-1"?>
 <reference id="ref.session">
  <title>Session Funktionen</title>
  <titleabbrev>Sessions</titleabbrev>

  <partintro>
   <para>
    Die Untersttzung von Sessions in PHP bietet die
    Mglichkeit, bestimmte Daten whrend einer Folge
    von Aufrufen ihrer Website festzuhalten. Damit knnen Sie
    persnlichere Applikationen erstellen und Ihre Website
    ansprechender gestalten.
   </para>
   <para>
    Falls sie mit dem Sessionmanagment von PHPLIB vertraut sind,
    werden sie hnlichkeiten zu PHP's Session-Untersttzung
    feststellen.
   </para>
   <para>
    Einem Besucher wird beim Aufruf ihrer Website eine einzigartige
    ID, die sogenannte Session-ID, zugeordnet. Diese wird entweder
    benutzerseitig in einem Cookie abgelegt oder in der URL
    bermittelt.
   </para>
   <para>
    Die Untersttzung von Sessions erlaubt Ihnen, eine beliebige
    Anzahl von Variablen zu registrieren und diese ber Anfragen
    hinweg zu erhalten. Wenn ein Besucher Ihre Website aufruft,
    berprft PHP automatisch (falls session.auto_start auf
    1 gesetzt ist) oder auf Anfrage (explizit durch
    <function>session_start</function> oder implizit durch
    <function>session_register</function>), ob mit der Anfrage schon
    eine bestimmte Session-ID gesendet wurde. Wenn dies der Fall ist,
    wird die zuvor gespeicherte Umgebung wiederhergestellt.
   </para>
   <para>
    Alle registrierten Variablen werden serialisiert, nachdem die
    Anfrage beendet ist. Registrierte Variablen, die nicht definiert
    sind, werden als nicht definiert gekennzeichnet. Auch bei
    darauffolgenden Zugriffen werden sie nicht vom Session-Modul
    definiert, auer der Benutzer definiert sie spter.
   </para>
   <para>
    Die Konfigurationseinstellungen von
    <link linkend="ini.track-vars"><literal>track_vars</literal></link>
    und
    <link linkend="ini.register-globals"><literal>register_globals</literal></link>
    beeinflussen, wie die Session-Variablen gespeichert und
    wiederhergestellt werden.
   </para> 
   <note>
    <para>
     Seit PHP 4.0.3 ist
     <link linkend="ini.track-vars"><literal>track_vars</literal></link>
     immer aktiviert.
    </para>
   </note>
   <note>
    <para>
     Seit PHP 4.1.0 steht <varname>$_SESSION</varname> genau wie
     <varname>$_POST</varname>, <varname>$_GET</varname>,
     <varname>$_REQUEST</varname> und so weiter, als globale Variable
     zur Verfgung. Im Gegensatz zu
     <varname>$HTTP_SESSION_VARS</varname> ist
     <varname>$_SESSION</varname> immer global. Deshalb sollte
     <literal>global</literal> nicht fr <varname>$_SESSION</varname>
     verwendet werden.
    </para>
   </note>
   <para>
    Falls
    <link linkend="ini.track-vars"><literal>track_vars</literal></link>
    aktiviert und
    <link linkend="ini.register-globals"><literal>register_globals</literal></link>
    deaktiviert ist, knnen nur Bestandteile des globalen assoziativen
    Arrays <varname>$HTTP_SESSION_VARS</varname> als Session-Variablen
    registriert werden. Wiederhergestellte Session-Variablen stehen
    nur im Array <varname>$HTTP_SESSION_VARS</varname> zur Verfgung.
    <example> 
     <title>
      Registrierung einer Variablen bei aktiviertem
      <link linkend="ini.track-vars"><literal>track_vars</literal></link>
     </title>
     <programlisting role="php">
<![CDATA[
<?php
if (isset($HTTP_SESSION_VARS['zaehler'])) {
   $HTTP_SESSION_VARS['zaehler']++;
}
else {
   $HTTP_SESSION_VARS['zaehler'] = 0;
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Aus Grnden der Sicherheit und der Lesbarkeit des Codes wird die
    Verwendung von <varname>$_SESSION</varname> (oder
    <varname>$HTTP_SESSION_VARS</varname> bei PHP 4.0.6 oder
    niedriger) empfohlen. Mit <varname>$_SESSION</varname> oder
    <varname>$HTTP_SESSION_VARS</varname> werden die Funktionen
    session_register()/session_unregister()/session_is_registered()
    nicht bentigt. Der Benutzer kann auf die Session-Variable wie auf
    eine normale Variable zugreifen.
    <example>
     <title>
      Registrierung einer Variablen mit $_SESSION.
     </title>
     <programlisting role="php">
<![CDATA[
<?php
// Verwenden Sie bei PHP 4.0.6 oder niedriger $HTTP_SESSION_VARS
if (!isset($_SESSION['zaehler'])) {
    $_SESSION['zaehler'] = 0;
}
else {
    $_SESSION['zarhler']++;
?>
]]>
     </programlisting>
    </example>
    <example>
     <title>
      Aufheben der Registrierung einer Variablen mit $_SESSION.
     </title>
     <programlisting role="php">
<![CDATA[
<?php
// Verwenden Sie bei PHP 4.0.6 oder niedriger $HTTP_SESSION_VARS
unset($_SESSION['zaehler']);
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Wenn
    <link linkend="ini.register-globals"><literal>register_globals</literal></link>
    aktiviert ist, knnen alle globalen Variablen als
    Session-Variablen registriert werden und die Session-Variablen
    werden als entsprechende globale Variablen wiederhergestellt.
    Da PHP wissen muss, welche globalen Variablen als
    Session-Variablen registriert sind, muss der Benutzer Variablen mit
    der Funktion session_register() registrieren, whrend
    <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>
    die Verwendung von session_register() nicht bentigt.
    <caution>
     <para>
      Wenn Sie
      <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>
      verwenden und <link
      linkend="ini.register-globals"><literal>register_globals</literal></link>
      deaktivieren, sollten Sie <function>session_register</function>,
      <function>session_is_registered</function> und
      <function>session_unregister</function> nicht verwenden.
     </para>
     <para>
      Wenn sie <link
       linkend="ini.register-globals"><literal>register_globals</literal></link> aktivieren, sollten Sie <function>session_unregister</function>
       verwenden, weil beim Deserialisieren von Session-Daten die
       Session-Variablen als globale Variablen registriert werden. Die
       Deaktivierung von
       <link
       linkend="ini.register-globals"><literal>register_globals</literal></link>
       ist sowohl aus Sicherheitsgrnden als auch wegen
       der Performance empfehlenswert.
     </para>
    </caution>
    <example>
     <title>
      Registrierung einer Variablen bei aktiviertem
      <link linkend="ini.register-globals"><literal>register_globals</literal></link>
     </title>
     <programlisting role="php">
<![CDATA[
<?php
if (!session_is_registered('zaehler')) {
    session_register("zaehler");
    $zaehler = 0;
}
else {
    $zaehler++;
}
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Wenn sowohl
    <link linkend="ini.track-vars"><literal>track_vars</literal></link>
    als auch
    <link linkend="ini.register-globals"><literal>register_globals</literal></link>
    aktiviert sind, dann referenzieren die globalen Variablen und die
    Eintrge von
    <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>
    fr bereits registrierte Variablen den selben Wert.
   </para>
   <para>
    Wenn der Benutzer session_register() verwendet, um eine
    Session-Variable zu registrieren, befindet sich diese Variable
    nicht vor dem nchsten Laden aus dem Sessionspeicher (d.h. bei der
    nchsten Anfrage) im Array von
    <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>.
   </para>
   <para>
    Es gibt zwei Methoden, eine Session-ID zu bermitteln:
    <itemizedlist>
     <listitem>
      <simpara>
       Cookies
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       URL Parameter
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
   <para>
    Das Session-Modul untersttzt beide Methoden. Cookies sind
    optimal, aber da sie nicht zuverlssig sind (Clients mssen
    sie nicht unbedingt akzeptieren), knnen wir uns nicht auf sie
    verlassen. Die zweite Methode hngt die Session-ID direkt an die
    URLs.
   </para>
   <para>
    Wenn PHP mit
    <link
    linkend="install.configure.enable-trans-sid"><literal>--enable-trans-sid</literal></link>
    kompiliert wurde, kann es dies transparent machen. Wenn Sie diese
    Option aktivieren, werden relative URIs automatisch gendert,
    sodass sie die Session-ID enthalten. Alternativ knnen sie die
    Konstante <literal>SID</literal> verwenden, die definiert wird,
    falls vom Client keinen passendes Cookie gesendet wurde.
    <literal>SID</literal> hat entweder die Form
    <literal>session_name=session_id</literal> oder ist eine leere
    Zeichenkette.
   </para>
   <para>
    Das folgende Beispiel demonstriert, wie eine Variable registriert
    wird und wie unter Verwendung einer SID korrekt auf eine andere
    Seite verwiesen wird.
    <example>
     <title>Zhlen der Seitenaufrufe eines einzelnen Benutzers</title>
     <programlisting role="php">
<![CDATA[
<?php
if (!session_is_registered('zaehler')) {
    session_register('zaehler');
    $zaehler = 1;
}
else {
    $zaehler++;
}
?>

Hallo Besucher, Sie haben diese Seite <?php echo $zaehler; ?> Mal
aufgerufen.<p>

<?php
# fr den Fall, dass der Benutzer Cookies deaktiviert hat,
# ist das <?php echo SID?> ntig, um die Session-ID zu erhalten
# (wenn die Option short tag aktiviert ist, kann <?=SID?> verwendet
# werden)
?>

Hier gehts <A HREF="nextpage.php?<?php echo SID?>">weiter</A>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Das <literal>&lt;?=SID?&gt;</literal> ist nicht ntig, wenn PHP mit
    <link linkend="install.configure.enable-trans-sid"><literal>--enable-trans-sid</literal></link>
    kompiliert wurde.
   </para>
   <note>
    <para>
     Bei nichtrelativen URLs wird davon ausgegangen, dass sie auf
     externe Seiten zeigen und, weil es ein Sicherheitsrisiko wre,
     die SID an einen anderen Server zu bermitteln, von daher keine
     SID angehngt.
    </para>
   </note>
   <para>
    Wenn Sie die Speicherung in einer Datenbank oder irgendeine andere
    Art der Speicherung realisieren wollen, mssen Sie
    <function>session_set_save_handler</function> verwenden, um eine
    Reihe von benutzerdefinierten Speicherfunktionen zu erzeugen.
   </para>
   <para>
    Das Sessionmanagementsystem untersttzt eine Anzahl von
    Konfigurationsoptionen, die sie in Ihrer php.ini setzen knnen. Wir
    geben Ihnen dazu einen kleinen berblick.
    <itemizedlist>
     <listitem>
      <simpara>
       <literal>session.save_handler</literal> definiert den Namen der
       Prozedur, die benutzt wird, um die Daten zu speichern und
       zurckzuholen, die mit der Session in Verbindung
       stehen. Grundeinstellung <literal>files</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.save_path</literal> definiert das Argument,
       das an die Speicherprozedur bergeben wird. Wenn Sie die
       standardmige files Prozedur whlen, ist das der Pfad, unter
       dem die Dateien erzeugt werden. Grundeinstellung
       <literal>/tmp</literal>. Wenn die Verzeichnistiefe von
       <literal>session.save_path</literal> grer als zwei ist, wird
       die garbage collection nicht durchgefhrt.
      </simpara>
      <warning>
       <para>
        Wenn Sie ein Verzeichnis gewhlt haben, fr das jeder
        Leserechte hat, wie das z.B. bei /tmp (Grundeinstellung) der
        Fall ist, knnten andere Serverbenutzer mit Hilfe der
        Dateiliste dieses Verzeichnisses Ihre Sessions entfhren.
       </para>
      </warning>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.name</literal> spezifiziert den Namen der
       Session, der als Cookie-Name verwendet wird. Grundeinstellung
       <literal>PHPSESSID</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.auto_start</literal> spezifiziert, ob das
       Session-Modul zu Beginn einer Anfrage automatisch eine Session
       startet.  Grundeinstellung <literal>0</literal> (deaktiviert).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.cookie_lifetime</literal> spezifiziert die
       Cookie-Lebensdauer, die an den Browser geschickt wird, in
       Sekunden. Der Wert 0 bedeutet "bis der Browser geschlossen
       wird." Grundeinstellung <literal>0</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.serialize_handler</literal> definiert den
       Namen der Prozedur, die benutzt wird, um Daten zu
       serialisieren/deserialisieren.  Gegenwrtig wird ein internes
       PHP-Format (Name <literal>php</literal>) und WDDX (name
       <literal>wddx</literal>) untersttzt. WDDX steht nur zur
       Verfgung, wenn PHP mit <link linkend="ref.wddx">WDDX
       support</link> kompiliert wurde.  Grundeinstellung
       <literal>php</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.gc_probability</literal> spezifiziert die
       prozentuale Wahrscheinlichkeit, dass die gc (garbage
       collection) Routine bei jeder Anfrage gestartet
       wird. Grundeinstellung <literal>1</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.gc_maxlifetime</literal> spezifiziert die
       Anzahl der Sekunden, nach denen Daten als 'garbage' ('Mll')
       betrachtet und entsorgt werden.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.referer_check</literal> enthlt die
       Zeichenkette, auf die Sie jeden HTTP-Referer berprfen
       wollen. Wenn der Referer vom Client gesendet und die
       Zeichenkette nicht gefunden wurde, wird die eingebettete
       Session-ID als ungltig gekennzeichnet. Grundeinstellung ist
       eine leere Zeichenkette.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.entropy_file</literal> gibt den Pfad zu einer
       externen Quelle (Datei) an, die bei der Erzeugung einer
       Session-ID als zustzliche Entropiequelle verwendet
       wird. Beispiele sind <literal>/dev/random</literal> oder
       <literal>/dev/urandom</literal>, die auf vielen Unix-Systemen
       zur Verfgung stehen.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.entropy_length</literal> spezifiziert die
       Anzahl der Bytes, die von der oben spezifizierten Datei gelesen
       werden. Grundeinstellung <literal>0</literal> (deaktiviert).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.use_cookies</literal> spezifiziert, ob das
       Modul Cookies verwendet, um die Session-ID clientseitig zu
       speichern. Grundeinstellung <literal>1</literal> (aktiviert).
      </simpara>
     </listitem>
     <listitem>
      <simpara> 
       <literal>session.cookie_path</literal> spezifiziert den Pfad,
       in dem das Session-Cookie gesetzt wird. Grundeinstellung
       <literal>/</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.cookie_domain</literal> spezifiziert die
       Domain, unter der das Session-Cookie gesetzt wird. In der
       Grundeinstellung berhaupt keine.
      </simpara>
     </listitem>
     <listitem> 
      <simpara> 
       <literal>session.cache_limiter</literal> spezifiziert die
       Methode der Cacheverwaltung, die bei Session-Seiten benutzt
       wird (none/nocache/private/private_no_expire/public).
       Grundeinstellung <literal>nocache</literal>.
      </simpara>
     </listitem>
     <listitem> 
      <simpara> 
       <literal>session.cache_expire</literal> spezifiziert in
       Minuten, wie lange Session-Seiten im Cache bleiben. Bei nocache
       ist diese Angabe wirkungslos. Grundeinstellung
       <literal>180</literal>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>session.use_trans_sid</literal> bestimmt, wenn
       mit
       <link linkend="install.configure.enable-trans-sid"><literal>--enable-trans-sid</literal></link>
       kompiliert wurde, ob transparente SID-Untersttzung aktiviert
       ist oder nicht. Grundeinstellung <literal>1</literal>
       (aktiviert).
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       <literal>url_rewriter.tags</literal> bestimmt, wenn
       Untersttzung fr transparente SID aktiviert ist, welche
       HTML-Tags so umgeschrieben werden, dass sie die Session-ID
       beinhalten. Grundeinstellung
       <literal>a=href,area=href,frame=src,input=src,form=fakeentry</literal>
      </simpara>
     </listitem>
    </itemizedlist>
    <note>
     <para>
      Die Behandlung von Sessions wurde in PHP 4.0 eingefhrt.
     </para>
    </note>
   </para>
  </partintro>

  <refentry id="function.session-start">
   <refnamediv>
    <refname>session_start</refname>
    <refpurpose>Initialisiert eine Session</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>bool</type><methodname>session_start</methodname>
      <void/>
     </methodsynopsis>
    <simpara>
     <function>session_start</function> erzeugt eine Session (oder
     nimmt die aktuelle, basierend auf der Session-ID, die ber eine
     GET-Variable oder ein Cookie bermittelt wurde, wieder auf).
    </simpara>
    <simpara>
     Wenn Sie eine benannte Session verwenden wollen, mssen Sie
     <function>session_name</function> aufrufen, bevor Sie
     <function>session_start</function> aufrufen.
    </simpara>
    <simpara>
     Diese Funktion gibt immer &true; zurck.
    </simpara>
    <note>
     <para>
      Bei Verwendung Cookie-basierter Sessions mssen Sie
      <function>session_start</function> aufrufen, bevor irgend
      etwas an den Browser geschickt wird.
     </para>
    </note>
    <simpara>
     Wenn <literal>trans-sid</literal> aktiviert ist, registriert
     <function>session_start</function> die interne Ausgaberoutine fr
     das Umschreiben von URLs. Verwendet ein Benutzer
     <literal>ob_gzhandler</literal> oder hnliches mit
     <function>ob_start</function>, ist die Reihenfolge der
     Augaberoutine wichtig fr eine korrekte Ausgabe. Zum Beispiel
     muss der Benutzer <literal>ob_gzhandler</literal> vor Beginn der
     Session registrieren.
    </simpara>
    <note>
     <simpara>
      Die Verwendung von <literal>zlib.output_compression</literal>
      ist <literal>ob_gzhandler</literal> vorzuziehen.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.session-destroy">
   <refnamediv>
    <refname>session_destroy</refname>
    <refpurpose>
     Lscht alle in einer Session registrierten Daten
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>bool</type><methodname>session_destroy</methodname>
      <void/>
     </methodsynopsis>
    <simpara>
     <function>session_destroy</function> lscht alle in Verbindung
     mit der aktuellen Session stehenden Daten. Mit der Session
     zusammenhngende Globale Variablen und das Session-Cookie werden
     nicht gelscht.
    </simpara>
    <simpara>
     Diese Funktion gibt nach erfolgtem Lschen der Daten &true; zurck
     und &false;, wenn dabei ein Fehler auftritt.
    </simpara>
    <para>
     <example>
      <title>Lschen einer Session</title>
      <programlisting role="php">
<![CDATA[
<?php
// Initialisierung der Session.
// Wenn Sie session_name("irgendwas") verwenden, vergessen Sie es
// jetzt nicht!
session_start();
// Lschen aller Session-Variablen.
session_unset();
// Zum Schlu, lschen der Session.
session_destroy();

?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     <example>
      <title>Lschen einer Session mit $_SESSION</title>
      <programlisting role="php">
<![CDATA[
<?php

// Initialisierung der Session.
// Wenn Sie session_name("irgendwas") verwenden, vergessen Sie es
// jetzt nicht!
session_start();
// Lschen aller Session-Variablen.
unset($_SESSION);
// Zum Schlu, lschen der Session.
session_destroy();
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-name">
   <refnamediv>
    <refname>session_name</refname>
    <refpurpose>
     Liefert und/oder setzt den Namen der aktuellen Session
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>string</type><methodname>session_name</methodname>
      <methodparam choice="opt">
       <type>string</type><parameter>Name</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_name</function> gibt den Namen der aktuellen
     Session zurck. Wenn <parameter>Name</parameter> angegeben wird,
     wird der Name der aktuellen Session durch dessen Wert ersetzt.
    </para>
    <para>
     Der Session-Name referenziert die Session-ID in Cookies und
     URLs. Er sollte nur alphanumerische Zeichen enthalten und sollte
     kurz und beschreibend sein (z.B. fr Benutzer mit aktivierter
     Cookie-Warnung). Der Session-Name wird auf den Ausgangswert
     zurckgesetzt, der zu Beginn in <literal>session.name</literal>
     gespeichert wurde. Deshalb muss <function>session_name</function>
     bei jeder Anfrage aufgerufen werden (und bevor
     <function>session_start</function> oder
     <function>session_register</function> aufgerufen wurden).
    </para>
    <example>
     <title><function>session_name</function> Beispiele</title>
     <programlisting role="php">
<![CDATA[
<?php
// den Session-Namen auf WebsiteID setzen
$name_vorher = session_name ("WebsiteID");
echo "Der vorhergehende Session-Name war $name_vorher<p>";
?>
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.session-module-name">
   <refnamediv>
    <refname>session_module_name</refname>
    <refpurpose>
     Liefert und/oder setzt das aktuelle Session-Modul
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>string</type><methodname>session_module_name</methodname>
      <methodparam choice="opt">
       <type>string</type><parameter>Modul</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_module_name</function> gibt den Namen des
     aktuellen Session-Moduls zurck. Wenn
     <parameter>Modul</parameter> angegeben wird, wird stattdessen
     dieses Modul verwendet.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-save-path">
   <refnamediv>
    <refname>session_save_path</refname>
    <refpurpose>
     Liefert und/oder setzt den aktuellen Speicherpfad der Session
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
      <methodsynopsis>
      <type>string</type><methodname>session_save_path</methodname>
      <methodparam choice="opt">
       <type>string</type><parameter>Pfad</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_save_path</function> gibt den Pfad des
     aktuellen Verzeichnisses zurck, das zum Speichern der
     Session-Daten verwendet wird. Wenn <parameter>Pfad</parameter>
     angegeben wird, wird der Pfad, unter dem Daten gespeichert
     werden, entsprechend gendert.
     <note>
      <para>
       Unter manchen Betriebssystemen, wollen Sie vielleicht einen
       Pfad auf einem Dateisystem angeben, das sehr viele kleine
       Dateien effizient behandelt. Unter Linux, zum Beispiel, bietet
       reiserfs eventuell eine bessere Performance als ext2fs.
      </para>
     </note>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-id">
   <refnamediv>
    <refname>session_id</refname>
    <refpurpose>
     Liefert und/oder setzt die aktuelle Session-ID
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>string</type><methodname>session_id</methodname>
      <methodparam choice="opt">
       <type>string</type><parameter>ID</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_id</function> gibt die Session-ID der aktuellen
     Session zurck. Wenn <parameter>ID</parameter> angegeben wird,
     wird die die aktuelle Session-ID ersetzt.
    </para>
    <para>
     Die Konstante <systemitem>SID</systemitem> kann auch dazu
     verwendet werden, den aktuellen Namen und die Session-ID als
     Zeichenkette passend zum Anhngen an URLs zu erhalten.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-register">
   <refnamediv>
    <refname>session_register</refname>
    <refpurpose>
     Registriert eine oder mehrere Variablen in der aktuellen Session
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>bool</type><methodname>session_register</methodname>
      <methodparam>
       <type>mixed</type><parameter>Name</parameter>
      </methodparam>
      <methodparam choice="opt">
       <type>mixed</type><parameter>...</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_register</function> akzeptiert eine variable
     Anzahl von Argumenten, die jeweils entweder eine Zeichenkette
     sein knnen, die den Namen einer Variablen trgt, oder ein Array,
     das aus solchen Variablennamen oder anderen Arrays besteht. Fr
     jeden Namen registriert <function>session_register</function>
     die globale Variable mit diesem Namen in der aktuellen Session.
    </para>
    <caution>
     <para>
      Diese Funktion registriert eine <emphasis>globale</emphasis>
      Variable. Wenn Sie eine Session-Variable innerhalb einer
      Funktion registrieren wollen, mssen Sie sicherstellen, dass Sie
      sie mittels <function>global</function> global machen oder Sie
      verwenden die nachstehend vermerkten Session-Arrays.
     </para>
    </caution>
    <caution>
     <para>
      Wenn Sie
      <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>
      verwenden, sollten Sie <function>session_register</function>,
      <function>session_is_registered</function> und
      <function>session_unregister</function> nicht verwenden.
     </para>
    </caution>
    <para>
     Diese Funktion gibt &true; zurck, wenn alle Variablen
     erfolgreich in der Session registriert wurden.
    </para>
    <para>
     Wenn <function>session_start</function> nicht vor dieser Funktion
     aufgerufen wurde, erfolgt ein impliziter Aufruf von
     <function>session_start</function> ohne Parameter.
    </para>
    <para>
     Sie knnen eine Session-Variable auch erzeugen, indem Sie das
     entsprechende Element des <varname>$HTTP_SESSION_VARS</varname>-
     oder (PHP >= 4.1.0) <varname>$_SESSION</varname>-Arrays
     setzen.
     <informalexample>
      <programlisting role="php">
<![CDATA[
$barney = "A big purple dinosaur.";
session_register("barney");

$HTTP_SESSION_VARS["zim"] = "An invader from another planet.";

# Das auto-global $_SESSION-Array wurde mit PHP 4.1.0 eingefhrt
$_SESSION["spongebob"] = "He's got square pants.";
]]>
      </programlisting>
     </informalexample>
    </para>
    <note>
     <para>
      Gegenwrtig ist es nicht mglich, Ressourcen-Variablen in einer
      Session zu registrieren. Zum Beispiel knnen Sie nicht erwarten,
      dass die als Session-Variable gespeicherte Verbindungs-Kennung
      der zu einer Datenbank aufgebauten Verbindung bei der nchsten
      Wiederherstellung der Session noch gltig ist. PHP-Funktionen,
      die eine Ressource zurckgeben, knnen daran erkannt werden,
      dass sie einen Rckgabewert <literal>resource</literal> in ihrer
      Funktionsdefinition haben. Eine Liste der Funktionen, die
      Ressourcen zurckgeben befindet sich im Anhang
      <link linkend="resource">Liste von PHP Ressourcen</link>.
     </para>
     <para>
      Bei Verwendung von <varname>$_SESSION</varname> (oder
      <varname>$HTTP_SESSION_VARS</varname> bei PHP 4.0.6 oder
      niedriger) weisen Sie <varname>$_SESSION</varname> eine Variable
      zu, also $_SESSION['var'] = 'ABC';
     </para>
    </note>
    <para>
     Siehe auch: <function>session_is_registered</function> und
     <function>session_unregister</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-unregister">
   <refnamediv>
    <refname>session_unregister</refname>
    <refpurpose>
     Hebt die Registrierung einer Variablen in der aktuellen Session
     auf
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>bool</type><methodname>session_unregister</methodname>
      <methodparam>
       <type>string</type><parameter>Name</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_unregister</function> hebt die Registrierung
     der globalen Variablen namens <parameter>Name</parameter> in der
     aktuellen Session auf.
    </para>
    <para>
     Diese Funktion gibt &true; zurck, wenn die Aufhebung der
     Registrierung der Variablen in der Session erfolgt ist.
    </para>
    <note>
     <para>
      Benutzen Sie bei Verwendung von <varname>$_SESSION</varname>
      (oder <varname>$HTTP_SESSION_VARS</varname> bei PHP 4.0.6 oder
      niedriger) <function>unset</function> um die Registrierung einer
      Session-Variablen aufzuheben.
     </para>
    </note>
    <caution>
     <para>
      Diese Funktion lscht die <parameter>Name</parameter>
      entsprechende globale Variable nicht, sondern verhindert nur,
      dass die Variable als Teil der Session gespeichert wird. Sie
      mssen <function>unset</function> aufrufen, um die entsprechende
      globale Variable zu entfernen.
     </para>
    </caution>
    <caution>
     <para>
      Wenn Sie
      <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>
      verwenden, sollten Sie <function>session_register</function>,
      <function>session_is_registered</function> und
      <function>session_unregister</function> nicht verwenden.
     </para>
    </caution>
   </refsect1>
  </refentry>

  <refentry id="function.session-unset">
   <refnamediv>
    <refname>session_unset</refname>
    <refpurpose>
     Befreit alle Session-Variablen
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>void</type><methodname>session_unset</methodname>
      <void/>
     </methodsynopsis>
    <para>  
     Die Funktion <function>session_unset</function> befreit alle
     Session-Variablen, die gegenwrtig registriert sind.
    </para>
    <note>
     <para>
      Benutzen Sie bei Verwendung von <varname>$_SESSION</varname>
      (oder <varname>$HTTP_SESSION_VARS</varname> bei PHP 4.0.6 oder
      niedriger) <function>unset</function> um die Registrierung einer
      Session-Variablen aufzuheben, also unset($_SESSION);
     </para>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.session-is-registered">
   <refnamediv>
    <refname>session_is_registered</refname>
    <refpurpose>
     berprft, ob eine Variable in einer Session registriert ist
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>bool</type><methodname>session_is_registered</methodname>
      <methodparam>
       <type>string</type><parameter>Name</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_is_registered</function> gibt &true; zurck,
     wenn in der aktuellen Session eine Variable mit dem Namen
     <parameter>Name</parameter> registriert ist.
    </para>
    <note>
     <para>
      Benutzen Sie bei Verwendung von <varname>$_SESSION</varname>
      (oder <varname>$HTTP_SESSION_VARS</varname> bei PHP 4.0.6 oder
      niedriger) <function>isset</function> um zu prfen, ob eine
      Variable in <varname>$_SESSION</varname> registriert ist.
     </para>
    </note>
    <caution>
     <para>
      Wenn Sie
      <varname>$HTTP_SESSION_VARS</varname>/<varname>$_SESSION</varname>
      verwenden, sollten Sie <function>session_register</function>,
      <function>session_is_registered</function> und
      <function>session_unregister</function> nicht verwenden.
     </para>
    </caution>
   </refsect1>
  </refentry>
  
  <refentry id="function.session-get-cookie-params">
   <refnamediv> 
    <refname>session_get_cookie_params</refname>
    <refpurpose>  
     Liefert die Session-Cookie Parameter
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>array</type><methodname>session_get_cookie_params</methodname>
      <void/>
     </methodsynopsis>
    <para>
     Die Funktion <function>session_get_cookie_params</function> gibt
     ein Array mit der Information des aktuellen Session-Cookies
     zurck. Das Array enthlt folgende Elemente:
     <itemizedlist>
      <listitem>      
       <simpara>
        "lifetime" - Die Lebensdauer des Cookies.
       </simpara>     
      </listitem>
      <listitem>
       <simpara>
        "path" - Der Pfad, unter dem Informationen gespeichert sind.
       </simpara>
      </listitem>     
      <listitem>
       <simpara>      
        "domain" - Die Domain des Cookies.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        "secure" - Das Cookie soll nur ber sichere Verbindungen
        gesendet werden. (Dieses Element wurde in PHP 4.0.4
        hinzugefgt.)
       </simpara>
      </listitem>
     </itemizedlist>   
    </para>
   </refsect1>
  </refentry>  

  <refentry id="function.session-set-cookie-params">
   <refnamediv>
    <refname>session_set_cookie_params</refname>
    <refpurpose>
     Setzt die Session-Cookie Parameter
    </refpurpose>  
   </refnamediv>   
   <refsect1>      
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>void</type><methodname>session_set_cookie_params</methodname>
      <methodparam>
       <type>int</type><parameter>Lebensdauer</parameter>
      </methodparam>
      <methodparam choice="opt">
       <type>string</type><parameter>Pfad</parameter>
      </methodparam>   
      <methodparam choice="opt">
       <type>string</type><parameter>Domain</parameter>
      </methodparam>   
     </methodsynopsis>
    <para>
     Setzen der Cookie-Parameter, die in der php.ini definiert
     sind. Diese Funktion wirkt sich nur fr die Dauer des Scripts
     aus.
    </para>
   </refsect1> 
  </refentry>

  <refentry id="function.session-decode">
   <refnamediv>
    <refname>session_decode</refname>
    <refpurpose>
     Dekodiert die Daten einer Session aus einer Zeichenkette
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>bool</type><methodname>session_decode</methodname>
      <methodparam>
       <type>string</type><parameter>Daten</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_decode</function> dekodiert die Daten der
     Session in <parameter>Daten</parameter> und setzt die Variablen,
     die in der Session gespeichert sind.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-encode">
   <refnamediv>
    <refname>session_encode</refname>
    <refpurpose>
     Kodiert die Daten der aktuellen Session als Zeichenkette
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>string</type><methodname>session_encode</methodname>
      <void/>
     </methodsynopsis>
    <para>
     <function>session_encode</function> gibt eine Zeichenkette mit
     dem kodierten Inhalt der aktuellen Session zurck.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-set-save-handler">
   <refnamediv>
    <refname>session_set_save_handler</refname>
    <refpurpose>
     Setzt benutzerdefinierte Session-Speicherfunktionen
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>void</type><methodname>session_set_save_handler</methodname>
      <methodparam>
       <type>string</type><parameter>ffnen</parameter>
      </methodparam>
      <methodparam>
       <type>string</type><parameter>schlieen</parameter>
      </methodparam>
      <methodparam>
       <type>string</type><parameter>lesen</parameter>
      </methodparam>
      <methodparam>
       <type>string</type><parameter>schreiben</parameter>
      </methodparam>
      <methodparam>
       <type>string</type><parameter>lschen</parameter>
      </methodparam>
      <methodparam>
       <type>string</type><parameter>gc</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_set_save_handler</function> setzt die
     benutzerdefinierten Session-Speicherfunktionen, die zur
     Speicherung und Wiederherstellung von zur Session gehrigen Daten
     verwendet werden. Dies ist uerst ntzlich, wenn eine andere als
     die mit PHP-Sessions zur Verfgung stehende Art der Speicherung,
     z.B. die Speicherung der Session-Daten in einer lokalen
     Datenbank, bevorzugt wird.
   </para>
    <note>
     <para>
      Sie mssen in Ihrer php.ini-Datei die Konfigurationsoption
      <parameter>session.save_handler</parameter> auf
      <parameter>user</parameter> setzen, damit
      <function>session_set_save_handler</function> wirksam wird.
     </para>
    </note>
    <note>
     <para>
      Die "schreiben"-Routine wird nicht ausgefhrt, bevor die Ausgabe
      abgeschlossen ist. Deshalb werden auch niemals Fehlermeldungen
      der "schreiben"-Routine im Browser erscheinen. Wenn die Ausgabe
      von Fehlermeldungen ntig ist, sollte diese stattdessen in eine
      Datei geschrieben werden.
     </para>
    </note>
    <para>
     Das folgende Beispiel liefert eine dateibasierte
     Session-Speicherung, die der Standard-Speicherroutine
     <parameter>files</parameter> der PHP-Sessions hnlich ist. Dieses
     Beispiel kann problemlos erweitert werden, dass es
     Datenbank-Speicherung mittels ihrer bevorzugten PHP-gesttzten
     Datenbank beinhaltet.
    </para>
    <para>
     Damit die Speicherroutine funktioniert wie erwartet, muss die
     read-Function immer einen String-Wert zurckgeben. Wenn es keine
     Daten zu lesen gibt, geben Sie eine leere Zeichenkette zurck.
     Rckgabewerte anderer Routinen werden in boolesche Ausdrcke
     umgewandelt. TRUE fr einen Erfolg, FALSE fr einen Fehler.
    </para>
    <para>
     <example>
      <title>
       <function>session_set_save_handler</function> Beispiel
      </title>
      <programlisting role="php">
<![CDATA[
<?php
function open ($save_path, $session_name) {
  global $sess_save_path, $sess_session_name;

  $sess_save_path = $save_path;
  $sess_session_name = $session_name;
  return(true);
}

function close() {
  return(true);
}

function read ($id) {
  global $sess_save_path, $sess_session_name;

  $sess_file = "$sess_save_path/sess_$id";
  if ($fp = @fopen($sess_file, "r")) {
    $sess_data = fread($fp, filesize($sess_file));
    return($sess_data);
  } else {
    return(""); // Must return "" here.
  }

}

function write ($id, $sess_data) {
  global $sess_save_path, $sess_session_name;

  $sess_file = "$sess_save_path/sess_$id";
  if ($fp = @fopen($sess_file, "w")) {
    return(fwrite($fp, $sess_data));
  } else {
    return(false);
  }

}

function destroy ($id) {
  global $sess_save_path, $sess_session_name;
       
  $sess_file = "$sess_save_path/sess_$id";
  return(@unlink($sess_file));
}

/************************************************
 * WARNUNG - Sie mssen hier irgendeine Art von *
 * Speicherbereinigungsroutine realisieren.     *
 ************************************************/
function gc ($maxlifetime) {
  return true;
}

session_set_save_handler ("open", "close", "read", "write", "destroy",
"gc");

session_start();

// verfahren Sie mit Sessions wie gewohnt
?>
]]>
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-cache-limiter">
   <refnamediv>
    <refname>session_cache_limiter</refname>
    <refpurpose>
     Liefert und/oder setzt die aktuelle Cacheverwaltung
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>string</type><methodname>session_cache_limiter</methodname>
      <methodparam choice="opt">
       <type>string</type><parameter>Cacheverwaltung</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_cache_limiter</function> gibt die Bezeichnung
     der aktuellen Cacheverwaltung zurck. Wenn
     <parameter>Cacheverwaltung</parameter> angegeben wurde, wird
     diese dem neuen Wert entsprechend gendert.
    </para>
    <para>
     Die Cacheverwaltung steuert die Cache-Kontrolle der HTTP-Header,
     die zum Client geschickt werden. Diese Header bestimmen die
     Regel, nach der der Seiteninhalt in den Cachespeicher aufgenommen
     wird. Wird die Cacheverwaltung beispielsweise auf
     <literal>nocache</literal> gesetzt, ist eine clientseitige
     Speicherung im Cache nicht erlaubt. Andererseits erlaubt der Wert
     <literal>public</literal> die Aufnahme in den Cachespeicher. Sie
     kann auch auf <literal>private</literal> gesetzt werden, was
     etwas restriktiver ist, als <literal>public</literal>.
    </para>
    <para>
     Im <literal>private</literal>-Modus knnte ein zum Client
     gesendeter Expire-Header manche Browser, inklusive Mozilla,
     verwirren. Sie knnen dieses Problem mit dem
     <literal>private_no_expire</literal>-Modus vermeiden. In diesem
     Modus wird nie ein Expire-Header zum Client gesendet.
    </para>
    <note>
     <para>
      <literal>private_no_expire</literal> wurde in PHP 4.2.0dev
      hinzugefgt.
     </para>
    </note>
    <para>
     Zu Beginn einer Anfrage wird die Cacheverwaltung auf den
     voreingestellten Wert zurckesetzt, der in
     <literal>session.cache_limiter</literal> gespeichert ist. Daher
     mssen Sie <function>session_cache_limiter</function> bei jeder
     Anfrage aufrufen (und zwar bevor
     <function>session_start</function> aufgerufen wird).
    </para>
    <example>
     <title><function>session_cache_limiter</function> Beispiel</title>
     <programlisting role="php">
<![CDATA[
<?php
# setzen der Cacheverwaltung auf 'private'
session_cache_limiter('private');
$cacheverwaltung = session_cache_limiter();
echo "Die Cacheverwaltung ist jetzt auf $cacheverwaltung gesetzt<p>";
?>
]]>
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id='function.session-cache-expire'>
   <refnamediv>
    <refname>session_cache_expire</refname>
    <refpurpose>Liefert die aktuelle Cache-Verfallszeit</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>int</type><methodname>session_cache_expire</methodname>
      <methodparam choice="opt">
       <type>int</type><parameter>neue_cache_verfallszeit</parameter>
      </methodparam>
     </methodsynopsis>
    <para>
     <function>session_cache_expire</function> gibt die aktuelle
     Cache-Verfallszeit zurck. Wenn neue_cache_verfallszeit gegeben
     ist, wird die aktuelle cache_expire durch neue_cache_verfallszeit
     ersetzt.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.session-write-close">
   <refnamediv>
    <refname>session_write_close</refname>
    <refpurpose>
     Speichert die Session-Daten und beendet die Session
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>void</type><methodname>session_write_close</methodname>
      <void/>
     </methodsynopsis>
    <para>
     Beendet die aktuelle Session und speichert die Session-Daten.
    </para>
    <para>
     Session-Daten werden normalerweise nach Beenden eines Scripts
     gespeichert, ohne dass <function>session_write_close</function>
     aufgerufen werden muss, aber da Session-Daten gesperrt werden, um
     gleichzeitiges Schreiben zu verhindern, kann jeweils immer nur
     ein Script auf eine Session einwirken. Bei der Verwendung von
     Framesets zusammen mit Sessions werden Sie merken, dass wegen
     dieser Sperrung ein Frame nach dem anderen geladen wird. Sie
     knnen die Zeit zum Laden aller Frames reduzieren, indem Sie die
     Session beenden, sobald alle nderungen an den Session-Variablen
     durchgefhrt sind.
    </para>

<!-- commented out until final decision on implementation
    <para>
     See also: <function>session_readonly</function>.
    </para>
-->

   </refsect1>
  </refentry>

<!-- commented out until final decision on implementation
  <refentry id="function.session-readonly">
   <refnamediv>
    <refname>session_readonly</refname>
    <refpurpose>
     Begin session - reinitializes freezed variables, but no writeback
     on request end
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>session_readonly</methodname>
      <void/>
     </methodsynopsis>
    <para>
     Read in session data without locking the session data. Changing
     session data is not possible, but frameset performance will be
     improved.
    </para>
   </refsect1>
  </refentry>
-->

 </reference>

<!-- 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:"../../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
-->