diff --git a/reference/network/functions/setcookie.xml b/reference/network/functions/setcookie.xml index 6e70d8ba0..a2d85b251 100644 --- a/reference/network/functions/setcookie.xml +++ b/reference/network/functions/setcookie.xml @@ -1,6 +1,5 @@ - - + @@ -21,17 +20,14 @@ boolsecure&false; boolhttponly&false; - - Alternative Signatur, verfügbar ab PHP 7.3.0 (benannte Parameter werden - nicht unterstützt): - + Alternative Signatur, verfügbar ab PHP 7.3.0 (benannte Parameter werden nicht unterstützt): boolsetcookie stringname stringvalue"" arrayoptions[] - + setcookie definiert ein mit den HTTP-Header-Informationen zu übertragendes Cookie. Wie andere Header auch, müssen Cookies vor jeglicher Ausgabe des Skripts @@ -39,12 +35,12 @@ dass diese Funktion vor jeglicher Ausgabe, einschließlich der Ausgabe von <html>- oder <head>-Tags sowie jeder Art von Whitespace, aufgerufen werden muss. - - + + Sind die Cookies einmal gesetzt, kann beim nächsten Seitenaufruf anhand des $_COOKIE-Arrays auf diese zugegriffen werden. Die Cookie-Werte können auch in $_REQUEST vorhanden sein. - + @@ -57,27 +53,27 @@ name - + Der Name des Cookies. - + value - + Der Wert des Cookies. Dieser Wert wird auf dem Computer des Benutzers gespeichert, weshalb darin keine sensiblen Informationen gespeichert werden sollten. Angenommen der Parameter name ist 'cookiename', so erhält man seinen Wert mittels $_COOKIE['cookiename']. - + expires_or_options - + 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, @@ -88,24 +84,21 @@ mktime zu verwenden. Wenn dieser Parameter auf 0 gesetzt oder weggelassen wird, verfällt das Cookie am Ende der Session (wenn der Browser geschlossen wird). - - - - - Wie bestimmt aufgefallen ist, wird der Parameter - expires_or_options als Unix-Timestamp - übergeben und nicht im Datumsformat Wdy, DD-Mon-YYYY - HH:MM:SS GMT. Die Konvertierung wird von PHP intern - durchgeführt. - - - + + + + Der Parameter expires_or_options erwartet einen + Unix-Timestamp und nicht das Datumsformat Wdy, DD-Mon-YYYY + HH:MM:SS GMT, da die Konvertierung von PHP intern + durchgeführt wird. + + path - + Der Pfad auf dem Server, innerhalb dem das Cookie verfügbar sein wird. Ist er auf '/' gesetzt, wird das Cookie innerhalb der gesamten domain verfügbar. Ist er auf @@ -114,13 +107,13 @@ wie &zb; /foo/bar/ von domain verfügbar. Der Standardwert ist das aktuelle Verzeichnis, in dem das Cookie gesetzt wurde. - + domain - + Die (Sub)-Domain, der das Cookie zur Verfügung steht. Wird dies auf eine Subdomain (wie 'www.example.com') gesetzt, dann steht dieser Subdomain und allen anderen Subdomains davon (&zb; @@ -128,19 +121,19 @@ Domain zur Verfügung zu stellen (einschließlich aller Subdomains davon), muss der Wert einfach auf den Domainnamen (in diesem Fall 'example.com') gesetzt werden. - - + + Ältere Browser, die noch immer das veraltete RFC 2109 implementieren, können ein führendes . benötigen, um alle Subdomains abzudecken. - + secure - + 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 @@ -148,13 +141,13 @@ achten, dass entsprechende Cookies über eine sichere Verbindung gesendet werden (&zb; unter Berücksichtigung von $_SERVER["HTTPS"]). - + httponly - + 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 @@ -162,36 +155,43 @@ 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; - + options - + Ein assoziatives &array;, das die Schlüssel expires, path, domain, secure, httponly und samesite enthalten - kann. Ist irgendein anderer Schlüssel vorhanden, wird ein Fehler der - Stufe E_WARNING generiert. Die Werte haben - dieselbe Bedeutung wie für die gleichnamigen Parameter beschrieben. Der - Wert des samesite-Elements sollte entweder - None, Lax oder + kann. + + + Die Werte haben dieselbe Bedeutung wie für die gleichnamigen Parameter + beschrieben. Der Wert des samesite-Elements sollte + entweder None, Lax oder Strict sein. Ist eine der erlaubten Optionen nicht angegeben, dann ist ihr Standardwert derselbe wie für den expliziten Parameter. Wird das samesite-Element nicht angegeben, dann wird kein SameSite-Cookie-Attribut gesetzt. - - - - - Um ein Cookie mit Attributen zu setzen, die nicht unter den - aufgelisteten Schlüsseln sind, kann die Funktion - header verwendet werden. - - - + + + + + Um ein Cookie mit Attributen zu setzen, die nicht unter den + aufgelisteten Schlüsseln sind, kann die Funktion + header verwendet werden. + + + + + Wenn samesite auf "None" gesetzt + ist, muss auch secure aktiviert sein, da das Cookie + sonst vom Client blockiert wird. + + @@ -200,83 +200,115 @@ &reftitle.returnvalues; - + Erfolgt eine Ausgabe vor dem Aufruf dieser Funktion, wird setcookie fehlschlagen und &false; zurückgeben. Wenn setcookie erfolgreich durchgeführt wird, wird &true; zurückgegeben. Dies sagt jedoch nichts darüber aus, ob der Benutzer das Cookie auch akzeptiert hat. - + + + + + &reftitle.errors; + + Wenn das options-Array nicht unterstützte Schlüssel + enthält: + + + + + Vor PHP 8.0.0 wurde ein E_WARNING erzeugt. + + + + + Ab PHP 8.0.0 wird ein ValueError geworfen. + + + &reftitle.changelog; - - - - - - &Version; - &Description; - - - - - 8.2.0 - - Das Datumsformat des gesendeten Cookies ist nun - 'D, d M Y H:i:s \G\M\T'; vorher war es - 'D, d-M-Y H:i:s T'. - - - - 7.3.0 - - Eine alternative Signatur, die ein - options-Array unterstützt, wurde hinzugefügt. - Diese Signatur unterstützt auch das Setzen des - SameSite-Cookie-Attributs. - - - - - - + + + + + &Version; + &Description; + + + + + 8.2.0 + + Das Datumsformat des gesendeten Cookies ist nun + 'D, d M Y H:i:s \G\M\T'; vorher war es + 'D, d-M-Y H:i:s T'. + + + + 8.0.0 + + Die Übergabe nicht unterstützter Schlüssel wirft nun einen + ValueError, anstatt ein + E_WARNING auszulösen. + + + + 7.3.0 + + Eine alternative Signatur, die ein + options-Array unterstützt, wurde hinzugefügt. + Diese Signatur unterstützt auch das Setzen des + SameSite-Cookie-Attributs. + + + + + &reftitle.examples; - - Die folgenden Beispiele zeigen einige Möglichkeiten, Cookies zu senden. - - <function>setcookie</function>-Beispiele - + + Die Auswirkungen der folgenden Beispiele lassen sich in der Cookie-Liste + der Entwicklerwerkzeuge des Browsers beobachten (in der Regel im Tab + Speicher oder Anwendung). + + + <function>setcookie</function>-Beispiele + ]]> - - - - - 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 setrawcookie verwendet werden. Um die - Inhalte unseres Test-Cookies in einem Skript sichtbar zu machen, kann - einfach eines der folgenden Beispiele verwendet werden: - - - - + + + + Zu beachten ist, dass der Wertebereich des Cookies automatisch von PHP + URL-konform kodiert (urlencoded) und wieder dekodiert wird. Dies kann + vermieden werden, indem stattdessen setrawcookie + verwendet wird. + + + Um den Inhalt der im obigen Beispiel gesetzten Cookies in einem späteren + Request zu sehen: + + + ]]> - - - - - - <function>setcookie</function>-Beispiele zum Löschen - - 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: - - + + + + <function>setcookie</function>-Beispiele zum Löschen + + Um ein Cookie zu löschen, muss das Verfallsdatum auf einen Wert in der + Vergangenheit gesetzt werden (jedoch nicht auf null, was für + Session-Cookies reserviert ist). + + + Um die im vorigen Beispiel gesetzten Cookies zu löschen: + + ]]> - - - - - - <function>setcookie</function> und Arrays - - 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: - - + + + + <function>setcookie</function> und Arrays + + Mit der Array-Schreibweise im Cookienamen kann 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: + + ]]> - - &example.outputs; - + + &example.outputs; + - - - - - Die Verwendung von Trennzeichen wie [ und - ] 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. - - - + + + + + Die Verwendung von Trennzeichen wie [ und + ] 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. + + &reftitle.notes; - - 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 - ob_start und ob_end_flush oder - mittels der Konfigurationseinstellung output_buffering - in Ihrer &php.ini;, oder Sie ändern entsprechende - Konfigurationseinstellungen am Server. - + + Mit Hilfe der Ausgabepufferung lassen sich Ausgaben vor dem Aufruf dieser + Funktion zulassen. Alle Ausgaben werden gepuffert, bis sie geleert werden + (entweder explizit oder am Ende der Skriptausführung). Dies wird durch + Aufruf von ob_start und + ob_end_flush im Skript erreicht oder durch Aktivieren + der Konfigurationseinstellung output_buffering in der + &php.ini; oder in den Serverkonfigurationsdateien. + Häufige Probleme: @@ -378,8 +406,8 @@ eins : cookieeins 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 + gesetzt wurde, ist noch vor der Ablaufzeit auf der nächsten geladenen + Seite zu prüfen, ob das Cookie vorhanden ist. Die Ablaufzeit wird mittels des Parameters expires_or_options gesetzt. Eine gute Möglichkeit, die Existenz von Cookies zu prüfen, ist einfach print_r($_COOKIE); aufzurufen. @@ -399,20 +427,20 @@ eins : cookieeins 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 0 für &false; - und 1 für &true;. + entsprechende Cookie zu löschen, sollten keine boolschen Werte + verwendet werden. Stattdessen sollte 0 für &false; + und 1 für &true; verwendet werden. 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 explode, um ein Cookie mit - mehreren Namen und Werten zu setzen. Es ist nicht empfehlenswert, zu - diesem Zweck serialize einzusetzen, da hieraus - Sicherheitslöcher erwachsen können. + dann in den PHP-Skripten als Arrays zur Verfügung, während sie vom + Browser als separate Cookies abgespeichert werden. Es ist der Einsatz + von json_encode in Erwägung zu ziehen, um ein + Cookie mit mehreren Namen und Werten zu setzen. Es ist nicht + empfehlenswert, zu diesem Zweck serialize + einzusetzen, da hieraus Sicherheitslöcher erwachsen können. @@ -425,15 +453,13 @@ eins : cookieeins &reftitle.seealso; - - - header - setrawcookie - Cookies - RFC 6265 - RFC 2109 - - + + header + setrawcookie + Cookies + RFC 6265 + RFC 2109 +