- PHP Manual
- Netzwerk-Funktionen
- Sendet ein Cookie
setcookie
(PHP 4, PHP 5, PHP 7, PHP 8)
setcookie — Sendet ein Cookie
Beschreibung
string
$name,string
$value = "",int
$expires_or_options = 0,string
$path = "",string
$domain = "",bool
$secure = false,bool
$httponly = false): bool
Alternative Signatur, verfügbar ab PHP 7.3.0 (benannte Parameter werden nicht unterstützt):
$name, string $value = "", array $options = []): bool
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
nameist '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*30die Verfallszeit des Cookies auf 30 Tage. Eine weitere Möglichkeit ist, die Funktion mktime() zu verwenden. Wenn dieser Parameter auf0gesetzt oder weggelassen wird, verfällt das Cookie am Ende der Session (wenn der Browser geschlossen wird).Hinweis:
Wie bestimmt aufgefallen ist, wird der Parameter
expires_or_optionsals Unix-Timestamp übergeben und nicht im DatumsformatWdy, DD-Mon-YYYY HH:MM:SS GMT. Die Konvertierung wird von PHP intern durchgeführt. -
path -
Der Pfad auf dem Server, innerhalb dem das Cookie verfügbar sein wird. Ist er auf
'/'gesetzt, wird das Cookie innerhalb der gesamtendomainverfügbar. Ist er auf'/foo/'gesetzt, wird das Cookie nur innerhalb des Verzeichnisses/foo/sowie allen Unterverzeichnissen wie z. B./foo/bar/vondomainverfü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
truegesetzt, 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
truegesetzt, 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 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.trueoderfalse -
options -
Ein assoziatives Array, das die Schlüssel
expires,path,domain,secure,httponlyundsamesiteenthalten kann. Ist irgendein anderer Schlüssel vorhanden, wird ein Fehler der StufeE_WARNINGgeneriert. Die Werte haben dieselbe Bedeutung wie für die gleichnamigen Parameter beschrieben. Der Wert dessamesite-Elements sollte entwederNone,LaxoderStrictsein. Ist eine der erlaubten Optionen nicht angegeben, dann ist ihr Standardwert derselbe wie für den expliziten Parameter. Wird dassamesite-Element nicht angegeben, dann wird kein SameSite-Cookie-Attribut gesetzt.
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.
Changelog
| Version | Beschreibung |
|---|---|
| 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.
|
Beispiele
Einige Beispiele, wie Cookies gesetzt werden:
Beispiel #1 setcookie()-Beispiele:
<?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", 1);
?>
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:
<?php
// ein bestimmtes Cookie ausgeben
echo $_COOKIE["TestCookie"];
// Ein anderer Weg zu Debuggen/Testen ist, alle Cookies anzuzeigen
print_r($_COOKIE);
?>
Beispiel #2 setcookie()-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:
<?php
// Setzen des Verfalls-Zeitpunktes 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 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:
<?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:
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_bufferingin Ihrer php.ini, oder Sie ändern entsprechende Konfigurationseinstellungen am Server.
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, prüfen Sie noch vor der Ablaufzeit auf der nächsten
geladenen Seite, ob das Cookie vorhanden ist. Die Ablaufzeit wird
mittels des Parameters
expires_or_optionsgesetzt. Eine gute Möglichkeit, die Existenz von Cookies zu prüfen, ist einfachprint_r($_COOKIE);aufzurufen. -
Cookies müssen mit denselben Parametern gelöscht werden, mit denen sie
gesetzt wurden. Ist der value-Parameter ein leerer String und alle
anderen Werte entsprechen dem früheren Aufruf von setcookie, 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
falseversucht wird, das entsprechende Cookie zu löschen, sollten Sie keine boolschen Werte verwenden. Nutzen Sie statt dessen 0 fürfalseund 1 fürtrue. - 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.
Mehrfache Aufrufe von setcookie() werden in der Reihenfolge ihres Aufrufs ausgeführt.
Siehe auch
- header() - Sendet einen HTTP-Header in Rohform
- setrawcookie() - Sendet ein Cookie, ohne seinen Wert zu URL-kodieren
- Cookies
- » RFC 6265
- » RFC 2109
