setcookie() definiert ein mit den HTTP
Header-Informationen zu übertragendes Cookie. Wie andere Header auch,
müssen Cookies vor jeglicher Ausgabe Ihres Skriptes
gesendet werden (dies ist eine Einschränkung des Protokolls). Das bedeutet,
dass Sie diese Funktion aufrufen müssen, bevor Sie eine Ausgabe, dazu
zählen auch <html>- oder
<head>-Tags sowie jede Art von Whitespaces,
übermitteln.
Sind die Cookies einmal gesetzt, können Sie beim nächsten Seitenaufruf
anhand der $_COOKIE
oder $HTTP_COOKIE_VARS Arrays auf diese zugreifen.
Beachten Sie, dass die Superglobals wie
$_COOKIE seit PHP 4.1.0 verfügbar sind.
$HTTP_COOKIE_VARS existierte seit PHP 3. Die
Cookie-Werte stehen auch in $_REQUEST.
Parameter Liste
Alle Argumente außer name
sind optional. Sie können
ein Argument auch mit einem leeren String ("")
ersetzen, wenn Sie es übergehen wollen. Da der
expire
-Parameter einen Integer-Wert darstellt, kann
er nicht durch die Angabe eines Leerstrings übersprungen werden, verwenden
Sie daher statt dessen die Null (0).
Der Wert des Cookies. Dieser Wert wird auf dem Computer des Benutzers
gespeichert, speichern Sie deshalb darin keine sensiblen Informationen.
Angenommen der Parameter name
ist 'cookiename',
so erhält man seinen Wert mittels $_COOKIE['cookiename'].
expire
Der Zeitpunkt, an dem das Cookie ungültig wird. Dies ist ein Unix
Timestamp, also die Anzahl Sekunden seit Beginn der Epoche. Mit anderen
Worten, Sie werden diesen Wert wahrscheinlich mittels der Funktion
time() plus der Anzahl Sekunden bis zum gewünschten
Ablauf des Cookies setzen. Sie könnten aber auch mktime()
verwenden.
time()+60*60*24*30 wird das Cookie in 30 Tagen
ablaufen lassen. Hat der Parameter den Wert 0 oder ist er nicht
gesetzt, verfällt das Cookie am Ende der Session (wenn der Browser
geschlossen wird).
Hinweis:
Beachten Sie, dass der expire
-Parameter einen
Unix-Timestamp enthält, im Gegensatz zum Datumsformat Wdy,
DD-Mon-YYYY HH:MM:SS GMT. Die Konvertierung wird von PHP intern
durchgeführt.
expire
wird mit der lokalen Zeit des Clients verglichen,
da diese von der Server-Zeit differieren kann.
path
Der Pfad auf dem Server, für welchen 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/ der domain
verfügbar. Der Standardwert ist das aktuelle Verzeichnis, in dem das
Cookie gesetzt wurde.
domain
Die Domain, der das Cookie zur Verfügung steht.
Um das Cookie für alle Subdomains von example.com verfügbar zu
machen, setzen Sie es auf '.example.com'. Der
. ist zwar nicht erforderlich, macht die Angabe
aber zu mehr Browsern kompatibel. Ein Setzen auf
www.example.com macht das Cookie nur in der
Subdomain www verfügbar. Weitere Details hierzu
finden Sie in der » Spezifikation.
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. Der Standardwert ist FALSE. 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
zugreifbar. Das bedeutet, dass das Cookie nicht mehr für Skriptsprachen
wie JavaScript auslesbar/veränderbar ist. Diese Einstellung kann
eine effektive Hilfe sein, um Identitaetsdiebstahl per XSS-Angriff
zu vermindern (allerdings wird dies nicht von allen Browsern
unterstützt). Hinzugefügt in PHP 5.2.0.
TRUE oder FALSE
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.
Beachten Sie, dass der Wertebereich des Cookies automatisch URL-konform
kodiert (urlencoded) wird, sobald Sie das Cookie senden, und es beim Erhalt
automatisch dekodiert und einer Variablen zugewiesen wird, die den selben
Namen wie das Cookie trägt. Wenn Sie dies nicht möchten, können Sie
stattdessen setrawcookie() verwenden, wenn sie PHP 5
nutzen. Um die Inhalte unseres Test-Cookies in einem Skript sichtbar zu
machen, verwenden Sie einfach eines der folgenden Beispiele:
<?php // ein bestimmtes Cookie ausgeben echo $_COOKIE["TestCookie"]; echo $HTTP_COOKIE_VARS["TestCookie"];
// Ein anderer Weg zu Debuggen/Testen ist, alle Cookies anzuzeigen print_r($_COOKIE); ?>
Example#2 setcookie()-Beispiele zum Löschen
Beim Löschen eines Cookies sollten Sie sicherstellen, 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); ?>
Example#3 setcookie() und Arrays
Sie können auch ein Array von Cookies setzen, in dem Sie die
Array-Schreibweise im Cookienamen verwenden. Dadurch werden so viele
Cookies gesetzt, wie Ihr Array Elemente hat. Sobald das Cookie aber von
Ihrem Skript gelesen wird, werden alle Werte in ein einziges
Array mit dem Cookienamen eingelesen:
<?php // Setzen der Cookies setcookie ("cookie[three]", "cookiethree"); setcookie ("cookie[two]", "cookietwo"); setcookie ("cookie[one]", "cookieone");
// Nach dem Neuladen der Seite wieder ausgeben if (isset($_COOKIE['cookie'])) { foreach ($_COOKIE['cookie'] as $name => $value) { echo "$name : $value <br />\n"; } } ?>
Das oben gezeigte Beispiel erzeugt folgende
Ausgabe:
three : cookiethree
two : cookietwo
one : cookieone
Anmerkungen
Hinweis:
In PHP 4 können Sie 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 am 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 mitteilen, oder Sie ändern entsprechende
Konfigurationseinstellungen am Server.
Hinweis:
Ist die PHP-Direktive register_globals auf
on gesetzt, stehen die Cookies auch als eigene
Variablen zur Verfügung. In den nachstehenden Beispielen wird
$TextCookie also existieren. Es ist jedoch dringend
empfohlen, $_COOKIE zu verwenden.
Häufige Probleme:
Cookies werden nicht sichtbar, bevor nicht eine Seite geladen
wird, 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 expire
gesetzt. Eine gute Möglichkeit, die Existenz von Cookies zu prüfen, ist
einfach print_r($_COOKIE); aufzurufen.
Cookies müssen mit den selben Parametern gelöscht werden, mit
denen sie gesetzt wurden. Ist der value-Parameter ein leerer String oder
FALSE und alle anderen Werte entsprechen dem früheren Aufruf von
setcookie, wird das Cookie mit dem angegebenen Namen vom Client gelöscht.
Da beim Setzen eines Cookies mit dem Value 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 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.
In PHP 3 werden mehrfache Aufrufe von setcookie()
im selben Skript in umgekehrter Reihenfolge abgearbeitet. Sollten
Sie also ein Cookie löschen wollen bevor Sie ein anderes setzen,
sollten sie das Setzen vor dem Löschen vornehmen. Ab PHP 4 werden
mehrfache Aufrufe von setcookie() in der
Reihenfolge ihres Aufrufs ausgeführt.
Hinweis:
Microsofts Internet-Explorer 4 mit Service-Pack 1 geht nicht
korrekt mit Cookies um, die den Pfad-Parameter beinhalten.
Netscape Communicator 4.05 und Microsoft Internet Explorer 3.x
scheinen mit Cookies Probleme zu haben, wenn die Argumente für
Pfad und Zeit nicht angegeben sind.
