header

Podręcznik PHP
Poprzedni		Następny

Opis

int header ( string treść_nagłówka [, bool zamień [, int kod_odpowiedzi_http]] )

header() służy do wysłania surowego nagłówka HTTP. Zajrzyj do Specyfikacji HTTP 1.1 aby dowiedzieć się więcej na temat nagłówków HTTP.

Pierwszy argument opcjonalny zamień określa, czy funkcja ma zastąpić nagłówek tego samego typu przygotowany przez serwer, czy dodać jeszcze jeden. Domyślnie, oryginalny nagłówek zostanie zastąpiony, ale jeśli ustawisz ten argument na FALSE, to nowy nagłówek zostanie dodany do już istniejących. Na przykład:


<?php
header('WWW-Authenticate: Negociate');
header('WWW-Authenticate: NTLM', FALSE);
?>

Drugi argument opcjonalny kod_odpowiedzi_http pozwala narzucić określony kod odpowiedzi HTTP. (Argument ten jest dostępny w PHP 4.3.0 i wyższych).

Są dwa specjalne wywołania funkcji header. Pierwszym z nich jest każdy nagłówek zaczynający się od "HTTP/" (wielkość liter nie jest istotna). Nagłówka tego używa się do podania statusu zapytania HTTP. Na przykład, jeśli skonfigurowałeś serwer Apache aby używał skryptu PHP do wyświetlania komunikatów o brakujących plikach (za pomocą dyrektywy ErrorDocument), możesz chcieć wypróbować, czy skrypt generuje właściwy kod statusu.


<?php
header("HTTP/1.0 404 Not Found");
?>

Notatka: Status połączenia HTTP zawsze będzie wysłany w pierwszej linii odpowiedzi serwera, niezależnie od kolejności wywołania funkcji header(). Aktualnie ustalony status połączenia może zostać nadpisany nowym, wystarczy tylko po raz kolejny wywołać funkcję header(). Należy to jednak zrobić, nim nagłówki zostaną wysłane.

Notatka: W PHP 3 funkcja ta działa tylko, jeżeli PHP jest skompilowane jako moduł Apache'a. Identyczny rezultat do powyższego można uzyskać za pomocą nagłówka Status.
<?php header("Status: 404 Not Found"); ?>

Drugim specjalnym wywołaniem funkcji header jest nagłówek "Location:". W tej sytuacji, do klienta wysyłany jest nie tylko ten nagłówek, ale także status przekierowania REDIRECT (302), o ile inny status zapytania 3xx nie został już wysłany.


<?php
header("Location: http://www.example.com/"); /* Przekieruj przeglądarkę */
exit;                 /* Upewnij się, że kod poniżej nie zostanie wykonany 
                         po przekierowaniu. */
?>

Notatka: Protokół HTTP 1.1 wymaga bezwzględnego URI w nagłówku Location: włącznie z określeniem protokołu, nazwy hosta i bezwzględnej scieżki dostępu, ale niektóre klienty akceptują względne URI. Zwykle używa się $_SERVER['HTTP_HOST'], $_SERVER['PHP_SELF'] i funkcji dirname() by wygenerować bezwględny URI:
<?php
header("Location: http://".$_SERVER['HTTP_HOST']
                       ."/".dirname($_SERVER['PHP_SELF'])
                       ."/".$względny_url);
?>

Skrypty PHP często służą do generowania dynamiczej treści, która nie może być buforowana przez klienta czy serwer proxy. Pamięć cache (bufor) w większości tych urządzeń da się wyłączyć dzięki:


<?php
header ("Expires: Mon, 26 Jul 1997 05:00:00 GMT");    // data w przeszłości
header ("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT"); 
                                                      // ciągle modyfikowany
header("Cache-Control: no-store, no-cache, must-revalidate");  // HTTP/1.1
header("Cache-Control: post-check=0, pre-check=0", false);
header("Pragma: no-cache");                          // HTTP/1.0
?>

Notatka: Możesz zaobserwować, że strony nie są buforowane, nawet jeśli nie użyłeś wszystkich ww. nagłówków. Jest wiele sposobów, w jakie użytkownicy mogą skonfigurować swoje przeglądarki, aby zmienić standardowy sposób buforowania. Przez wysłanie powyższych nagłówków, powinno się udać ominąć wszystkie ustawienia pozwalające na zbuforowanie wyniku pracy twojego skryptu.
Dodatkowo, session_cache_limiter() i dyrektywa konfiguracyjna session.cache_limiter służą do automatycznego generowania nagłówków związanych z bufurowaniem, kiedy sesje są w użyciu.

Pamiętaj, że header() może być wywoływana jedynie do momentu nim zostanie wysłana jakakolwiek treść, tzn. znaczniki HTML, puste linie lub wynik pracy PHP. Jest to bardzo częsty błąd, gdzie skrypty z funkcjami include(), require() itp. mają spacje albo puste linie przed wywołaniem funkcji header(). Problem ten pojawia się również w skryptach opartych na pojedynczym pliku PHP/HTML.


<html>
<?php
// Ten kod powoduje powstanie błędu. Proszę zauważyć, że
// ponad wywołaniem funkcji header() znajduje się jakaś treść.
header('Location: http://www.na_przyklad.com/');
?>

Notatka: W PHP 4 można użyć buforowania wyjścia aby ominąć ten problem. Wszystko, co skrypt wyśle do przeglądarki zostanie zatrzymane na serwerze do momentu, kiedy pojawi się instrukcja wysłania danych. Można to zrobić za pomocą funkcji ob_start() i ob_end_flush(), lub ustawiając dyrektywę kofiguracyjną output_buffering w pliku php.ini lub w plikach konfiguracyjnych serwera.

Aby użytkownik został monitowany o zapisanie wysyłanych danych, takich jak np. wygenerowany plik PDF, można użyć nagłówka Content-Disposition aby podać zalecaną nazwę pliku i zmusić przeglądarkę do wyświetlenia okienka zapisu pliku.


<?php
// przesyłamy plik PDF
header("Content-type: application/pdf");

// ustawiamy jego nazwę na downloaded.pdf
header("Content-Disposition: attachment; filename=downloaded.pdf");

// treść znajduje się w pliku original.pdf
readfile('original.pdf');
?>

Notatka: W Microsoft Internet Explorer 4.01 jest błąd, który uniemożliwia wykorzystanie tego mechanizmu. Nie ma na to rozwiązania. Błąd, który zahacza o ten mechanizm, jest także w Microsoft Internet Explorer 5.5, jednak da się go ominąć aktualizując przeglądarkę poprzez Service Pack 2 lub późniejszy.

Notatka: Jeśli tryb bezpieczny jest włączony, uid skryptu jest dodane do części realm nagłówka WWW-Authenticate, jeśli ustawisz ten nagłówek (wykorzystuje się go do autoryzacji HTTP).

Patrz także: headers_sent(), setcookie(), i rozdział Autoryzacja HTTP.

Poprzedni	Spis treści	Następny
HTTP - obsługa protokołu	Początek rozdziału	headers_list