setcookieSendet ein Cookie
&reftitle.description;
boolsetcookiestringnamestringvalue""intexpires_or_options0stringpath""stringdomain""boolsecure&false;boolhttponly&false;
Alternative Signatur, verfügbar ab PHP 7.3.0 (benannte Parameter werden
nicht unterstützt):
boolsetcookiestringnamestringvalue""arrayoptions[]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.
&reftitle.parameters;
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).
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.
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
'/foo/' gesetzt, wird das Cookie nur innerhalb des
Verzeichnisses /foo/ sowie allen Unterverzeichnissen
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;
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 (&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
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;
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
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.
&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.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.
&reftitle.examples;
Die folgenden Beispiele zeigen einige Möglichkeiten, Cookies zu senden.
<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:
]]>
<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> 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:
$value) {
$name = htmlspecialchars($name);
$value = htmlspecialchars($value);
echo "$name : $value \n";
}
}
?>
]]>
&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.
&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.
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_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 Sie keine boolschen Werte
verwenden. Nutzen Sie statt dessen 0 für &false;
und 1 für &true;.
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.
&reftitle.seealso;
headersetrawcookieCookiesRFC 6265RFC 2109