Forum und email
header
Podręcznik PHP
PoprzedniNastępny

header

(PHP 3, PHP 4, PHP 5)

header -- WysyÅ‚a surowy nagÅ‚owek HTTP

Opis

void 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.

Notatka: Począwszy od PHP 4.4.2 i PHP 5.1.2 funkcja nie pozwala na wysłanie więcej niż jednego nagłówka za jednym razem jest to zabezpieczenie przeciwko atakom typu iniekcja nagłowka (header injection).

Argument opcjonalny zamień określa, czy funkcja ma zastąpić nagłówek tego samego typu, czy dodać jeszcze jeden. Domyślnie, zostanie zastąpiony, ale jeśli ustawisz ten argument na FALSE, możesz wymusić wielokrotne nagłowki tego samego typu. 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 do klienta w pierwszej linii, niezależnie od kolejności wywołania funkcji header(). Status może być nadpisany w dowolnym momencie - dopóki nagłowki HTTP nie zostały wysłane - poprzez wywołanie header() z nową linią statusu.

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 kod statusu 3xx nie został już wysłany.

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

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ć samemu bezwględny URI ze względnego:

<?php
/* Przekieruj do innej strony w tym samym katalogu z którego nastąpiło żądanie */
$host  = $_SERVER['HTTP_HOST'];
$uri   = rtrim(dirname($_SERVER['PHP_SELF']), '/\\');
$extra = 'mypage.php';
header("Location: https://$host$uri/$extra");
exit;
?>

Notatka: Identyfikator sesji nie jest przekazywany w nagłówku Location chociażby session.use_trans_sid był włączony. Musi zostać przekazany ręcznie używając stałej SID.

Skrypty PHP często służą do generowania dynamiczej treści, która nie może być buforowana przez klienta czy serwer proxy znajdujący się pomiędzy serwerem a przeglądarką klienta. Wiele klientów i proxy można zmusić do wyłączenia buforowania za pomocą:

<?php
header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");    // data w przeszÅ‚oÅ›ci
?>

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() musi być wywołany przed wysłaniem jakiejkolwiek treści także znaczników HTML, pustych lini w pliku lub z PHP. Jest to bardzo częsty błąd, gdzie skrypty z funkcjami include(), require() lub innymi operującymi na plikach, 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: https://www.na_przyklad.com/');
?>

Notatka: Od PHP 4 można użyć buforowania wyjścia aby ominąć ten problem. Wszystko, co skrypt przesyła do przeglądarki zostanie przechowane na serwerze dopóki tego nie wyślesz. 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ł zapytany 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.

PoprzedniSpis treściNastępny
getservbyportPoczątek rozdziału