session-start.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 151e61773c016edcae8fd4989ad9a86ffd03c283 Maintainer: samesch Status: ready -->
<!-- Reviewed: yes Maintainer: samesch -->
<refentry xml:id="function.session-start" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>session_start</refname>
  <refpurpose>Erzeugt eine neue Session oder setzt eine vorhandene fort</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>session_start</methodname>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>session_start</function> erzeugt eine Session oder nimmt die
   aktuelle wieder auf, die auf der Session-Kennung basiert, die mit einer
   GET- oder POST-Anfrage oder mit einem Cookie übermittelt wurde.
  </para>
  <para>
   Wenn <function>session_start</function> aufgerufen wird oder eine Session
   automatisch startet, ruft PHP die Öffnen- und Lesen-Routinen der
   Session-Speicherroutine auf. Dies ist entweder eine eingebaute
   Speicherroutine, die standardmäßig mitgeliefert wird oder von
   Erweiterungen (wie &zb; SQLite oder Memcached) zur Verfügung gestellt
   wird, oder eine eigene Routine, die mittels
   <function>session_set_save_handler</function> definiert wurde. Die
   Lesen-Routine ruft alle vorhandenen Session-Daten (abgespeichert in einem
   speziellen serialisierten Format) ab und deserialisiert sie, um damit die
   $_SESSION-Superglobale zu füllen.
  </para>
  <para>
   Um eine benannte Session zu verwenden, rufen Sie
   <function>session_name</function> auf, bevor Sie
   <function>session_start</function> aufrufen.
  </para>
  <para>
   Wenn <link linkend="ini.session.use-trans-sid">session.use_trans_sid</link>
   aktiviert ist, registriert die Funktion <function>session_start</function>
   eine interne Ausgaberoutine für das Umschreiben von URLs.
  </para>
  <para>
   Verwendet ein Benutzer <literal>ob_gzhandler</literal> oder ähnliches mit
   <function>ob_start</function>, dann ist die Reihenfolge der Funktionen
   wichtig für eine korrekte Ausgabe. Zum Beispiel muss
   <literal>ob_gzhandler</literal> vor Beginn der Session registriert werden.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>options</parameter></term>
    <listitem>
     <para>
      Als optionaler Parameter kann ein assoziatives Array mit Optionen
      angegeben werden, das die aktuell gesetzten
      <link linkend="session.configuration">Session-Konfigurationsanweisungen</link>
      überschreibt. Die Schlüssel sollten nicht das
      <literal>session.</literal>-Präfix beinhalten.
     </para>
     <para>
      Zusätzlich zu den normalen Konfigurationsanweisungen kann auch eine
      <literal>read_and_close</literal>-Option angegeben werden. Falls auf
      &true; gesetzt, führt sie dazu, dass die Session unmittelbar nach dem
      Auslesen geschlossen wird. Dadurch lässt sich eine unnötige Sperre
      vermeiden, wenn die Session-Daten nicht verändert werden.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Falls die Session erfolgreich gestartet wurde, gibt diese Funktion &true;
   zurück, andernfalls &false;.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.1.0</entry>
       <entry>
        <function>session_start</function> gibt nun &false; zurück und
        initialisiert <varname>$_SESSION</varname> nicht mehr, wenn das
        Starten der Session fehlschlug.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <refsect2>
   <title>Ein grundlegendes Session-Beispiel</title>
   <para>
    <example>
     <title><filename>seite1.php</filename></title>
     <programlisting role="php">
<![CDATA[
<?php
// seite1.php

session_start();

echo 'Willkommen auf Seite #1';

$_SESSION['farbe'] = 'grün';
$_SESSION['tier'] = 'Spinne';
$_SESSION['zeit'] = time();

// Funktioniert, falls das Session-Cookie akzeptiert wurde
echo '<br /><a href="seite2.php">Seite 2</a>';

// Oder die Session-ID mit übergeben, für den Fall, dass sie benötigt wird
echo '<br /><a href="seite2.php?' . SID . '">Seite 2</a>';
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Nach dem Aufruf von <filename>seite1.php</filename> enthält automatisch
    auch die zweite Seite, <filename>seite2.php</filename>, die Session-Daten.
    Lesen Sie <link linkend="ref.session">Session-Funktionen</link>, um
    weitere Informationen über die
    <link linkend="session.idpassing">Übermittlung der Session-ID</link> zu
    erhalten. Dort wird zum Beispiel erklärt, worum es sich bei der Konstanten
    <constant>SID</constant> handelt.
   </para>
   <para>
    <example>
     <title><filename>seite2.php</filename></title>
     <programlisting role="php">
<![CDATA[
<?php
// seite2.php

session_start();

echo 'Willkommen auf Seite #2<br />';

echo $_SESSION['farbe'];  // grün
echo $_SESSION['tier'];   // Spinne
echo date('d.m.Y H:i:s', $_SESSION['zeit']);

// Sie können auch hier, genauso wie bei seite1.php, SID verwenden
echo '<br /><a href="seite1.php">Seite 1</a>';
?>
]]>
     </programlisting>
    </example>
   </para>
  </refsect2>
  <refsect2>
   <title>Optionen an <function>session_start</function> übergeben</title>
   <example>
    <title>Die Cookie-Gültigkeitsdauer übersteuern</title>
    <programlisting role="php">
<![CDATA[
<?php
// Ein persistentes Cookie senden, das einen Tag lang gültig ist.
session_start([
    'cookie_lifetime' => 86400,
]);
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>Die Session lesen und schließen</title>
    <programlisting role="php">
<![CDATA[
<?php
// Sofern wir wissen, dass wir keine Daten zu verändern brauchen,
// können wir die Session unmittelbar nach dem Auslesen automatisch
// schließen, um eine Sperre für die Session zu vermeiden und
// andere Seiten während der Zeit nicht am Zugriff zu hindern.
session_start([
    'cookie_lifetime' => 86400,
    'read_and_close'  => true,
]);
]]>
    </programlisting>
   </example>
  </refsect2>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Um Cookie-basierte Sessions zu verwenden muss
    <function>session_start</function> aufgerufen werden, bevor irgend etwas
    an den Browser geschickt wird.
   </para>
  </note>
  <note>
   <para>
    Die Verwendung von
    <link linkend="ini.zlib.output-compression">zlib.output_compression</link>
    ist <function>ob_gzhandler</function> vorzuziehen.
   </para>
  </note>
  <note>
   <para>
    In Abhängigkeit von der Konfiguration sendet diese Funktion verschiedene
    HTTP-Header. Siehe <function>session_cache_limiter</function>, um diese
    Header anzupassen.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><varname>$_SESSION</varname></member>
    <member>
     Die Konfigurationsanweisung
     <link linkend="ini.session.auto-start">session.auto_start</link>
    </member>
    <member><function>session_id</function></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
-->