reference/network/functions/setcookie.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1ad4e2d550953000e2441b663226300596962ef2 Maintainer: sammywg Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: 7f99d5e488d161ce3b12d1dae405a283728933c3 Reviewer: samesch -->
<refentry xml:id="function.setcookie" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>setcookie</refname>
  <refpurpose>Sendet ein Cookie</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>expires_or_options</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>path</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>domain</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>secure</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Alternative Signatur, verfügbar ab PHP 7.3.0 (benannte Parameter werden
   nicht unterstützt):
  </para>
  <methodsynopsis>
   <type>bool</type><methodname>setcookie</methodname>
   <methodparam><type>string</type><parameter>name</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>value</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>setcookie</function> definiert ein mit den
   HTTP-Header-Informationen zu übertragendes Cookie. Wie andere Header auch,
   müssen Cookies <emphasis>vor</emphasis> jeglicher Ausgabe des Skripts
   gesendet werden (dies ist eine Einschränkung des Protokolls). Das bedeutet,
   dass diese Funktion vor jeglicher Ausgabe, einschließlich der Ausgabe von
   <literal>&lt;html&gt;</literal>- oder <literal>&lt;head&gt;</literal>-Tags
   sowie jeder Art von Whitespace, aufgerufen werden muss.
  </para>
  <para>
   Sind die Cookies einmal gesetzt, kann beim nächsten Seitenaufruf anhand des
   <varname>$_COOKIE</varname>-Arrays auf diese zugegriffen werden. Die
   Cookie-Werte können auch in <varname>$_REQUEST</varname> vorhanden sein.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <link xlink:href="&url.rfc;6265">RFC 6265</link> liefert die normative
   Referenz, wie die jeweiligen <function>setcookie</function>-Parameter
   interpretiert werden.
   <variablelist>
    <varlistentry>
     <term><parameter>name</parameter></term>
     <listitem>
      <para>
       Der Name des Cookies.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>value</parameter></term>
     <listitem>
      <para>
       Der Wert des Cookies. Dieser Wert wird auf dem Computer des Benutzers
       gespeichert, weshalb darin keine sensiblen Informationen gespeichert
       werden sollten. Angenommen der Parameter <parameter>name</parameter>
       ist 'cookiename', so erhält man seinen Wert mittels
       <varname>$_COOKIE['cookiename']</varname>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>expires_or_options</parameter></term>
     <listitem>
      <para>
       Der Zeitpunkt, an dem das Cookie ungültig wird. Dies ist ein
       Unix-Timestamp, also die Anzahl Sekunden seit Beginn der Unix-Epoche
       (1. Januar 1970). Eine Möglichkeit, diesen festzulegen, besteht darin,
       die Anzahl der Sekunden, bevor das Cookie abläuft, zum Ergebnis des
       Aufrufs von <function>time</function> zu addieren. Zum Beispiel setzt
       <literal>time()+60*60*24*30</literal> die Verfallszeit des Cookies auf
       30 Tage. Eine weitere Möglichkeit ist, die Funktion
       <function>mktime</function> zu verwenden. Wenn dieser Parameter auf
       <literal>0</literal> gesetzt oder weggelassen wird, verfällt das Cookie
       am Ende der Session (wenn der Browser geschlossen wird).
      </para>
      <para>
       <note>
        <para>
         Wie bestimmt aufgefallen ist, wird der Parameter
         <parameter>expires_or_options</parameter> als Unix-Timestamp
         übergeben und nicht im Datumsformat <literal>Wdy, DD-Mon-YYYY
         HH:MM:SS GMT</literal>. Die Konvertierung wird von PHP intern
         durchgeführt.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <para>
       Der Pfad auf dem Server, innerhalb dem das Cookie verfügbar sein wird.
       Ist er auf <literal>'/'</literal> gesetzt, wird das Cookie innerhalb
       der gesamten <parameter>domain</parameter> verfügbar. Ist er auf
       <literal>'/foo/'</literal> gesetzt, wird das Cookie nur innerhalb des
       Verzeichnisses <literal>/foo/</literal> sowie allen Unterverzeichnissen
       wie &zb; <literal>/foo/bar/</literal> von <parameter>domain</parameter>
       verfügbar. Der Standardwert ist das aktuelle Verzeichnis, in dem das
       Cookie gesetzt wurde.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>domain</parameter></term>
     <listitem>
      <para>
       Die (Sub)-Domain, der das Cookie zur Verfügung steht. Wird dies auf
       eine Subdomain (wie <literal>'www.example.com'</literal>) gesetzt, dann
       steht dieser Subdomain und allen anderen Subdomains davon (&zb;
       w2.www.example.com) das Cookie zur Verfügung. Um das Cookie der ganzen
       Domain zur Verfügung zu stellen (einschließlich aller Subdomains
       davon), muss der Wert einfach auf den Domainnamen (in diesem Fall
       <literal>'example.com'</literal>) gesetzt werden.
      </para>
      <para>
       Ältere Browser, die noch immer das veraltete
       <link xlink:href="&url.rfc;2109">RFC 2109</link> implementieren, können
       ein führendes <literal>.</literal> benötigen, um alle Subdomains
       abzudecken.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secure</parameter></term>
     <listitem>
      <para>
       Gibt an, dass das Cookie vom Client nur über eine sichere
       HTTPS-Verbindung übertragen werden soll. Ist der Wert auf &true;
       gesetzt, wird das Cookie nur gesendet, wenn eine sichere Verbindung
       besteht. Auf der Serverseite muss der Programmierer selbst darauf
       achten, dass entsprechende Cookies über eine sichere Verbindung
       gesendet werden (&zb; unter Berücksichtigung von
       <varname>$_SERVER["HTTPS"]</varname>).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>httponly</parameter></term>
     <listitem>
      <para>
       Wenn auf &true; gesetzt, ist das Cookie nur via HTTP-Protokoll
       zugänglich. Das bedeutet, dass das Cookie nicht mehr für Skriptsprachen
       wie &zb; JavaScript, auslesbar/veränderbar ist. Es wird vermutet, dass
       diese Einstellung eine effektive Hilfe sein kann, um
       Identitätsdiebstahl per XSS-Angriff zu vermindern (obwohl sie nicht von
       allen Browsern unterstützt wird), diese Behauptung wird jedoch oft
       angezweifelt. &true; oder &false;
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       Ein assoziatives <type>&array;</type>, das die Schlüssel
       <literal>expires</literal>, <literal>path</literal>,
       <literal>domain</literal>, <literal>secure</literal>,
       <literal>httponly</literal> und <literal>samesite</literal> enthalten
       kann. Ist irgendein anderer Schlüssel vorhanden, wird ein Fehler der
       Stufe <constant>E_WARNING</constant> generiert. Die Werte haben
       dieselbe Bedeutung wie für die gleichnamigen Parameter beschrieben. Der
       Wert des <literal>samesite</literal>-Elements sollte entweder
       <literal>None</literal>, <literal>Lax</literal> oder
       <literal>Strict</literal> sein. Ist eine der erlaubten Optionen nicht
       angegeben, dann ist ihr Standardwert derselbe wie für den expliziten
       Parameter. Wird das <literal>samesite</literal>-Element nicht
       angegeben, dann wird kein SameSite-Cookie-Attribut gesetzt.
      </para>
      <para>
       <note>
        <para>
         Um ein Cookie mit Attributen zu setzen, die nicht unter den
         aufgelisteten Schlüsseln sind, kann die Funktion
         <function>header</function> verwendet werden.
        </para>
       </note>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Erfolgt eine Ausgabe vor dem Aufruf dieser Funktion, wird
   <function>setcookie</function> fehlschlagen und &false; zurückgeben. Wenn
   <function>setcookie</function> erfolgreich durchgeführt wird, wird &true;
   zurückgegeben. Dies sagt jedoch nichts darüber aus, ob der Benutzer das
   Cookie auch akzeptiert hat.
  </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>8.2.0</entry>
       <entry>
        Das Datumsformat des gesendeten Cookies ist nun
        <literal>'D, d M Y H:i:s \G\M\T'</literal>; vorher war es
        <literal>'D, d-M-Y H:i:s T'</literal>.
       </entry>
      </row>
      <row>
       <entry>7.3.0</entry>
       <entry>
        Eine alternative Signatur, die ein
        <parameter>options</parameter>-Array unterstützt, wurde hinzugefügt.
        Diese Signatur unterstützt auch das Setzen des
        SameSite-Cookie-Attributs.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   Die folgenden Beispiele zeigen einige Möglichkeiten, Cookies zu senden.
   <example>
    <title><function>setcookie</function>-Beispiele</title>
    <programlisting role="php">
<![CDATA[
<?php

$value = 'irgendetwas von irgendwo';

setcookie("TestCookie", $value);
setcookie("TestCookie", $value, time()+3600);  /* verfällt in 1 Stunde */
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Zu beachten ist, dass der Wertebereich des Cookies automatisch URL-konform
   kodiert (urlencoded) wird, sobald das Cookie gesendet wird, und es beim
   Erhalt automatisch dekodiert und einer Variablen zugewiesen wird, die
   denselben Namen wie das Cookie trägt. Wenn dies nicht gewünscht ist, kann
   stattdessen <function>setrawcookie</function> verwendet werden. Um die
   Inhalte unseres Test-Cookies in einem Skript sichtbar zu machen, kann
   einfach eines der folgenden Beispiele verwendet werden:
  </para>
  <para>
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php
// ein bestimmtes Cookie ausgeben
echo $_COOKIE["TestCookie"];

// Ein anderer Weg zu Debuggen/Testen ist, alle Cookies anzuzeigen
print_r($_COOKIE);
?>
]]>
    </programlisting>
   </informalexample>
  </para>
  <para>
   <example>
    <title><function>setcookie</function>-Beispiele zum Löschen</title>
    <para>
     Beim Löschen eines Cookies sollte sichergestellt werden, dass das
     Verfallsdatum in der Vergangenheit liegt, um den Mechanismus zum Löschen
     des Cookies im Browser auszulösen. Die folgenden Beispiele zeigen, wie
     die im vorigen Beispiel gesendeten Cookies wieder gelöscht werden:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Setzen des Verfalls-Zeitpunktes auf 1 Stunde in der Vergangenheit
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>setcookie</function> und Arrays</title>
    <para>
     Mit der Array-Schreibweise im Cookienamen kann auch ein Array von Cookies
     gesetzt werden. Dadurch werden so viele Cookies gesetzt, wie das Array
     Elemente hat, aber wenn das Cookie vom Skript empfangen wird, werden alle
     Werte in ein einziges Array mit dem Cookienamen eingelesen:
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Setzen der Cookies
setcookie("cookie[drei]", "cookiedrei");
setcookie("cookie[zwei]", "cookiezwei");
setcookie("cookie[eins]", "cookieeins");

// Nach dem Neuladen der Seite wieder ausgeben
if (isset($_COOKIE['cookie'])) {
    foreach ($_COOKIE['cookie'] as $name => $value) {
        $name = htmlspecialchars($name);
        $value = htmlspecialchars($value);
        echo "$name : $value <br />\n";
    }
}
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
drei : cookiedrei
zwei : cookiezwei
eins : cookieeins
]]>
    </screen>
   </example>
   <note>
    <simpara>
     Die Verwendung von Trennzeichen wie <literal>[</literal> und
     <literal>]</literal> als Teil des Cookie-Namens ist nicht konform mit RFC
     6265, Abschnitt 4, soll aber laut RFC 6265, Abschnitt 5, von User-Agents
     unterstützt werden.
    </simpara>
   </note>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Sie können den Ausgabepuffer verwenden, um Ausgaben vor dem Aufruf dieser
    Funktion duchführen zu können. Dies hat allerdings zur Folge, dass alle
    Ihre Ausgaben zum Browser auf dem Server zwischengespeichert werden, bis
    Sie diese senden. Sie können dies in Ihrem Skript mittels der Funktionen
    <function>ob_start</function> und <function>ob_end_flush</function> oder
    mittels der Konfigurationseinstellung <literal>output_buffering</literal>
    in Ihrer &php.ini;, oder Sie ändern entsprechende
    Konfigurationseinstellungen am Server.
   </para>
  </note>
  <para>
   Häufige Probleme:
   <itemizedlist>
    <listitem>
     <simpara>
      Cookies werden erst beim nächsten Laden einer Seite sichtbar, für die
      das Cookie sichtbar sein soll. Um zu testen, ob ein Cookie erfolgreich
      gesetzt wurde, prüfen Sie noch vor der Ablaufzeit auf der nächsten
      geladenen Seite, ob das Cookie vorhanden ist. Die Ablaufzeit wird
      mittels des Parameters <parameter>expires_or_options</parameter>
      gesetzt. Eine gute Möglichkeit, die Existenz von Cookies zu prüfen, ist
      einfach <literal>print_r($_COOKIE);</literal> aufzurufen.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Cookies müssen mit denselben Parametern gelöscht werden, mit denen sie
      gesetzt wurden. Wenn der Parameter <parameter>value</parameter> ein
      leerer String ist und alle anderen Werte dem vorherigen Aufruf von
      <function>setcookie</function> entsprechen, wird das Cookie mit dem
      angegebenen Namen vom Client gelöscht. Dies wird intern ausgeführt,
      indem der Wert auf <literal>'deleted'</literal> gesetzt wird und die
      Verfallszeit in die Vergangenheit gelegt wird.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Da beim Setzen eines Cookies mit dem Wert &false; versucht wird, das
      entsprechende Cookie zu löschen, sollten Sie keine boolschen Werte
      verwenden. Nutzen Sie statt dessen <emphasis>0</emphasis> für &false;
      und <emphasis>1</emphasis> für &true;.
     </simpara>
    </listitem>
    <listitem>
     <simpara>
      Namen von Cookies können auch als Arraynamen gesetzt werden und stehen
      dann in Ihren Skripten als Arrays zu Verfügung, während sie auf dem
      System des Benutzers als separate Cookies abgespeichert werden. Erwägen
      Sie den Einsatz von <function>explode</function>, um ein Cookie mit
      mehreren Namen und Werten zu setzen. Es ist nicht empfehlenswert, zu
      diesem Zweck <function>serialize</function> einzusetzen, da hieraus
      Sicherheitslöcher erwachsen können.
     </simpara>
    </listitem>
   </itemizedlist>
  </para>
  <simpara>
   Mehrfache Aufrufe von <function>setcookie</function> werden in der
   Reihenfolge ihres Aufrufs ausgeführt.
  </simpara>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>header</function></member>
    <member><function>setrawcookie</function></member>
    <member><link linkend="features.cookies">Cookies</link></member>
    <member><link xlink:href="&url.rfc;6265">RFC 6265</link></member>
    <member><link xlink:href="&url.rfc;2109">RFC 2109</link></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
-->