setcookie
(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Sendet ein Cookie
Beschreibung
Alternative Signatur, verfügbar ab PHP 7.3.0 (benannte Parameter werden nicht unterstützt):
setcookie() definiert ein mit den
HTTP-Header-Informationen zu übertragendes Cookie. Wie andere Header auch,
müssen Cookies vor 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
<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.
Parameter-Liste
» RFC 6265 liefert die normative
Referenz, wie die jeweiligen setcookie()-Parameter
interpretiert werden.
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,
die Anzahl der Sekunden, bevor das Cookie abläuft, zum Ergebnis des
Aufrufs von time() zu addieren. Zum Beispiel setzt
time()+60*60*24*30 die Verfallszeit des Cookies auf
30 Tage. Eine weitere Möglichkeit ist, die Funktion
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).
Hinweis:
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, in dem das Cookie verfügbar sein wird.
Ist er auf '/' gesetzt, wird das Cookie innerhalb
der gesamten domain verfügbar. Ist er auf
'/foo/' gesetzt, wird das Cookie nur innerhalb des
Verzeichnisses /foo/ sowie allen Unterverzeichnissen
wie z. B. /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 (z. B.
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
'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
besteht. Auf der Serverseite muss der Programmierer selbst darauf
achten, dass entsprechende Cookies über eine sichere Verbindung
gesendet werden (z. B. 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 z. B. JavaScript, auslesbar/veränderbar ist. Es wird vermutet, dass
diese Einstellung helfen kann, Identitätsdiebstahl durch XSS-Angriffe zu
vermindern, auch wenn 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.
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.
Hinweis:
Um ein Cookie mit Attributen zu setzen, die nicht unter den
aufgelisteten Schlüsseln sind, kann die Funktion
header() verwendet werden.
Hinweis:
Wenn samesite auf "None" gesetzt
ist, muss auch secure aktiviert sein, da das Cookie
sonst vom Client blockiert wird.
Rückgabewerte
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.
Fehler/Exceptions
Wenn das options-Array nicht unterstützte Schlüssel
enthält:
Beispiele
Die Auswirkungen der folgenden Beispiele lassen sich in der Cookie-Liste
der Entwicklerwerkzeuge des Browsers beobachten (in der Regel im Tab
"Speicher" im Firefox oder "Anwendung" in Chrome).
Beispiel #1 setcookie()-Beispiele
<?php
$value = 'irgendetwas von irgendwo';
// Setzt ein "Session-Cookie", das beim Schließen des Browsers verfällt
setcookie("TestCookie", $value);
// Setzt ein Cookie, das in 1 Stunde verfällt
setcookie("TestCookie", $value, time()+3600);
// Setzt ein Cookie, das nur für einen bestimmten Pfad einer bestimmten Domain gilt
// Es ist zu beachten, dass die verwendete Domain mit der Site-Domain übereinstimmen sollte
setcookie("TestCookie", $value, time()+3600, "/~rasmus/", "example.com", true);
?>
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:
Beispiel #2 setcookie()-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:
<?php
// Setzen des Verfallszeitpunktes auf 1 Stunde in der Vergangenheit
setcookie("TestCookie", "", time() - 3600);
setcookie("TestCookie", "", time() - 3600, "/~rasmus/", "example.com", 1);
?>
Beispiel #3 setcookie() 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:
<?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";
}
}
?>
Das oben gezeigte Beispiel erzeugt folgende Ausgabe:
drei : cookiedrei
zwei : cookiezwei
eins : cookieeins
Hinweis:
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.
Anmerkungen
Hinweis:
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:
-
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, 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.
-
Cookies müssen mit denselben Parametern gelöscht werden, mit denen sie
gesetzt wurden. Wenn der Parameter value ein
leerer String ist und alle anderen Werte dem vorherigen Aufruf von
setcookie() entsprechen, wird das Cookie mit dem
angegebenen Namen vom Client gelöscht. Dies wird intern ausgeführt,
indem der Wert auf 'deleted' gesetzt wird und die
Verfallszeit in die Vergangenheit gelegt wird.
-
Da beim Setzen eines Cookies mit dem Wert false versucht wird, das
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 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.
Mehrfache Aufrufe von setcookie() werden in der
Reihenfolge ihres Aufrufs ausgeführt.
