setcookie

(PHP 3, PHP 4 , PHP 5)

setcookie -- Poslat cookie

Popis

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

setcookie() definuje cookie, která se pošle spolu s ostatními HTTP hlavičkami. Podobně jako ostatní hlavičky, cookies se musí odeslat před jakýmkoliv výstupem vašeho skriptu (jedná se o omezení protokolu). Je tedy třeba, abyste všechna volání této funkce umístili před jakýkoliv výstup, včetně značek <html> a <head> a také před jakékoliv bílé znaky. Když je při volání této funkce už něco na výstupu, setcookie() neuspěje a vrátí FALSE. Když setcookie() proběhne v pořádku, vrátí TRUE. To však neříká nic o tom, zda byla cookie přijata klientem.

Poznámka: V PHP 4 lze k poslání výstupu před voláním této funkce použít output buffering, ovšem s tou režií, že všechen výstup pro prohlížeč bude pozdržen na serveru, dokud ho nepošlete. Lze to zařídit voláním funkcí ob_start() a ob_end_flush() nebo nastavením konfigurační direktivy output_buffering v php.ini nebo konfiguračních souborech serveru.

Všechny argumenty kromě argumentu name jsou nepovinné. Pokud je přítomný pouze argument name, u klienta se smaže cookie tohoto jména. Kterýkoliv argument můžete také nahradit prázdným řetězcem (""), čímž tento argument přeskočíte. Argumenty expire a secure jsou celočíselné a nedají se přeskočit prázdným řetězcem. Místo toho použijte nulu (0). Argument expire je běžné Unixové celočíselné vyjádření času, jak je vrací funkce time() či mktime(). Argument secure indikuje, že by se tato cookie měla přenášet pouze po zabezpečeném HTTPS spojení.

Běžné zádrhele:

V PHP 3 se vícenásobná volání setcookie() v jednom skriptu provedou v opačném pořadí. Pokud se pokoušíte smazat jeden cookie pře odesláním jiného, měli byste umístit vložení před smazání. V PHP 4 se vícenásobná volání setcookie() provedou v tom pořadí, jak jsou volána.

Několik příkladů, jak posílat cookies:

Příklad 1. Ukázky odeslání cookies pomocí setcookie()

setcookie ("TestCookie", "Zkušební hodnota");
setcookie ("TestCookie", $value,time()+3600);  /* vyprší za hodinu */
setcookie ("TestCookie", $value,time()+3600, "/~rasmus/", ".utoronto.ca", 1);

Následují příklady mazání cookies z předchozí ukázky:

Příklad 2. Ukázky mazání cookies pomocí setcookie()

setcookie ("TestCookie");
// nastaví dobu vypršení na čas před hodinou
setcookie ("TestCookie", "", time() - 3600);
setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".utoronto.ca", 1);
Při mazání cookie byste se měli ujistit, že je doba vypršení v minulosti, čímž se v browseru zapne mechanismus odstranění cookie.

Všimněte si, že hodnotová část cookie se při odeslání cookie automaticky url-zakóduje, a při přijetí se automaticky dekóduje a přiřadí proměnné stejného jména, jako je jméno cookie. Pokud chcete vidět obsah našeho zkušebního cookie, použijte některý z následujících příkladů:

echo $TestCookie;
echo $HTTP_COOKIE_VARS["TestCookie"];

Cookies obsahující pole můžete také odeslat tak, že za název cookie napíšete hranaté závorky. Účinkem tohoto je odeslání tolika cookies, kolik má vaše pole prvků, ale když váš skript tyto cookies přijme, hodnoty se umístí v poli stejného jména, jako jsou vaše cookies:

setcookie ("cookie[three]", "cookiethree");
setcookie ("cookie[two]", "cookietwo");
setcookie ("cookie[one]", "cookieone");
if (isset ($cookie)) {
    while (list ($name, $value) = each ($cookie)) {
        echo "$name == $value<br>\n";
    }
}

Více informací o cookies viz specifikace cookies na http://wp.netscape.com/newsref/std/cookie_spec.html.

Microsoft Internet Explorer 4 se Service Packem 1 zpracovává chybně cookies, které mají nastavený argument path.

Netscape Communicator 4.05 a Microsoft Internet Explorer 3.x zřejmě nezpracují cookies správně, pokud nejsou nastaveny argumenty path a time.