setcookie

Beschreibung

bool setcookie ( string name [, string value [, int expire [, string path [, string domain [, int secure]]]]])

setcookie() definiert ein mit den HTTP Header-Informationen zu übertragendes Cookie. Wie andere Header auch, müssen Cookies vor irgendwelchen anderen Ausgaben Ihres Skriptes gesendet werden (dies ist eine Einschränkung des Protokolls). Sie müssen deshalb solche Funktionsaufrufe vor irgendwelchen Ausgaben, inklusive <html>- oder <head>-Tags sowie irgendwelcher Whitespaces tätigen. Erfolgte bereits vor dem Aufruf dieser Funktion eine Ausgabe erfolgt sein, gibt setcookie() scheitern und FALSE zurückgeben. War setcookie() erfolgreich, wird TRUE zurückgegeben. Dies sagt jedoch nichts darüber aus, ob der Benutzer das Cookie auch akzeptiert hat.

Anmerkung: 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 den Funktionen ob_start() und ob_end_flush(), oder mittels der Konfigurationseinstellung output_buffering in Ihrer php.ini, oder durch Konfigurationseinstellungen am Server realisieren.

Alle Argumente - außer name - sind optional. Ist nur der Name angegeben wird das Cookie mit diesem Namen auf dem Client gelöscht. Sie können ein Argument auch durch einen Leerstring ("") ersetzen, um es zu überspringen. Da die Argumente expire und secure Integer-Werte sind können sie nicht mit einem Leerstring übersprungen werden. Setzen sie statt dessen NULL (0). Die folgende Tabelle erklärt jeden Parameter von setcookie(), spezifische Informationen finden Sie auch auf der Seite Netscape cookie specification.

Tabelle 1. setcookie() Parameter erklärt

Parameter	Beschreibung	Beispiele
`name`	Der Name des Cookies.	Auf 'cookiename' wird mittels `$_COOKIE['cookiename']` zugegriffen.
`value`	Der Wert des Cookies. Dieser Wert wird am Computer des Benutzers gespeichert, speichern Sie deshalb keine sensiblen Informationen.	Ist der `name` z.B. 'cookiename', so erhält man seinen Wert mittels `$_COOKIE['cookiename']`.
`expire`	Der Zeitpunkt, wann das verfällt. Dies ist ein Unix Timestamp, also die Anzahl Sekunden seit der Unix-Epoche. In anderen Worten werden Sie diesen Wert wahrscheinlich mittels der Funktion time() plus der Anzahl Sekunden bis zum gewünschten Ablauf des Cookies. Sie könnten aber auch mktime() verwenden.	`time()+606024*30` wird das Cookie in 30 Tagen ablaufen lassen. Ist der Parameter nicht gesetzt, verfällt das Cookie am Ende der Session (wenn der Browser geschlossen wird).
`path`	Der Pfad zu dem Server, auf welchem 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/` der `domain`, sowie allen Unterverzeichnissen wie z.B. `/foo/bar/` verfügbar. Der Standardwert ist das Verzeichnis, in dem das Cookie gesetzt wurde.
`domain`	Die Domain, der das Cookie zur Verfügung steht.	Um das Cookie für all Sub-Domains von example.com verfügbar zu machen, setzen Sie es auf `'.example.com'`. Der `.` ist zwar nicht erforderlich, erhöht aber die Kompatibilität zu mehr Browsern. Eine Setzen auf `www.example.com` macht das Cookie nur in der `www` Sub-Domain verfügbar. Weitere Details hierzu finden Sie in der Spezifikation.
`secure`	Gibt an, dass das Cookie nur über eine sichere HTTPS - Verbindung übertragen werden soll. Ist es auf `1` gesetzt, wird das Cookie nur gesendet, wenn eine sichere Verbindung besteht. Der Standardwert ist `0`.	`0` oder `1`

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 autoglobals wie $_COOKIE seit PHP 4.1.0 verfügbar sind. $HTTP_COOKIE_VARS existiert seit PHP 3. Cookie-Werte kommen auch in $_REQUEST vor.

Anmerkung: 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 wird empfohlen, $_COOKIE zu verwenden.

Häufige Probleme:

Cookies werden nicht sichtbar, bevor nicht eine Seite geladen wird, in der das Cookie sichtbar sein soll. Um zu testen, ob ein Cookie erfolgreich gesetzt wurde, prüfen Sie noch vor der Ablaufzeit auf einer weiteren Seite ob das Cookie vorhanden ist. Die Ablaufzeit wird mittels dem Parameter expire gesetzt. Eine nette Möglichkeit um die Existenz von Cookies zu prüfen, ist print_r($_COOKIE); aufzurufen.
Cookies müssen mit den selben Parametern gelöscht werden, mit denen sie gesetzt wurden.
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 separat abgespeichert werden. Um ein Cookie mit mehreren Namen und Werten zu setzen, erwägen Sie auch den Einsatz von explode() bzw. serialize().

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. In PHP 4 werden mehrfache Aufrufe von setcookie() in der Reihenfolge ihres Aufrufs behandelt.

Einige Beispiele, wie Cookies gesetzt / gesendet werden:
Beispiel 1. setcookie()-Beispiele:
<?php $value = 'something from somewhere'; setcookie ("TestCookie", $value); setcookie ("TestCookie", $value, time()+3600); /* verfällt in 1 Stunde */ setcookie ("TestCookie", $value, time()+3600, "/~rasmus/", ".utoronto.ca",1); ?>

Beachten Sie, dass der Wertebereich des Cookies automatisch URL-konform codiert (urlencoded) wird, sobald sie das Cookie senden, und wenn es gelesen wird, wird es automatisch URL-konform decodiert und einer Variablen zugewiesen, die den selben Namen wie das Cookie trägt. Um die Inhalte unserer Test-Cookies zu sehen, brauchen sie nur eines der folgenden Beispiele zu benutzen:


<?php
// ein bestimmtes Cookie ausgeben
echo $_COOKIE["TestCookie"];
echo $HTTP_COOKIE_VARS["TestCookie"];

// Eine anderer Weg zu debuggen/testen ist, alle Cookies anzuzeigen
print_r($_COOKIE);
?>

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:
Beispiel 2. setcookie() Beispiele zum Löschen
<?php // Setzen des Verfalls-Zeitpunktes auf 1 Stunde vorher setcookie ("TestCookie", "", time() - 3600); setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".example.com", 1); ?>

Sie können auch ein Array an Cookies setzen, in dem sie die Array-Schreibweise benutzen. 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 Cookie-Namen 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";
    }
}

/* was folgendes ausgibt:

three : cookiethree
two : cookietwo
one : cookieone

*/
?>

Weitere Informationen zu Cookies und deren Spezifikationen erhalten sie bei Netscape unter http://www.netscape.com/newsref/std/cookie_spec.html.

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.