Funzione PHP header(): Tutto Quello che Devi Sapere

Ogni risposta HTTP inviata da un server web è composta da due parti: un insieme di header (metadati come il tipo di contenuto, le regole di cache e il codice di stato) seguiti dal corpo della risposta (l'HTML, il JSON, l'immagine o il file che il browser riceve). La funzione header() di PHP ti consente di scrivere quegli header dal tuo script — così puoi reindirizzare gli utenti, servire download, impostare il tipo di contenuto, controllare la cache e inviare codici di stato personalizzati.

Questa guida copre la sintassi e i parametri di header(), l'unica regola che mette in difficoltà quasi tutti (l'errore "headers already sent"), e le ricette più comuni nella pratica reale.

Cos'è la funzione header()?

header() è una funzione PHP integrata che invia un header HTTP grezzo al client. Un header è una singola riga come Content-Type: text/html o Location: /login che il browser legge prima del corpo della pagina. Poiché gli header vengono prima nella risposta, header() funziona solo mentre PHP sta ancora costruendo quella sezione di header — vedi la regola "headers already sent" di seguito.

Sintassi e Parametri

header(string $header, bool $replace = true, int $response_code = 0): void

La funzione non restituisce nulla (void). Non ti indica se l'header è stato accettato — se l'output è già stato inviato, genera invece un avviso.

Impostare un header

L'utilizzo più semplice è dichiarare che tipo di contenuto contiene la risposta. Questo è essenziale quando il tuo script restituisce JSON, XML, testo semplice o un file invece di HTML:

<?php

header("Content-Type: application/json");

echo json_encode(["status" => "ok", "id" => 42]);

L'header Content-Type dice al browser di trattare il corpo come JSON, quindi analizza {"status":"ok","id":42} come dati anziché renderizzarlo come pagina web.

La regola "headers already sent"

Questa è la cosa più importante da sapere su header(): deve essere chiamata prima che qualsiasi output lasci il tuo script. L'output include HTML, echo/print, var_dump(), e persino uno spazio o una riga vuota prima del tag di apertura <?php. Una volta che un byte del corpo è stato inviato, la sezione degli header è chiusa e PHP genera:

Warning: Cannot modify header information - headers already sent

Hai due modi per evitarlo:

<?php

// 1. Check first — useful when a header is optional
if (!headers_sent()) {
    header("X-Powered-By: MyApp");
}

// 2. Buffer output so nothing is flushed until you choose to
ob_start();                 // capture everything that gets echoed
echo "page content...";
header("X-Cache: MISS");    // still works — body is held in the buffer
ob_end_flush();             // now send headers + buffered body together

Una causa comune è un editor che salva il file con un BOM UTF-8 o una nuova riga dopo ?>. Omettere del tutto il tag di chiusura ?> nei file PHP puri è il modo consigliato per evitarlo.

Casi d'uso comuni

Reindirizzare a un altro URL

Invia un header Location, poi interrompi lo script in modo che nessun ulteriore codice venga eseguito:

<?php

header("Location: https://example.com/login");
exit;   // always exit after a redirect

Per impostazione predefinita questo è un redirect 302 Found (temporaneo). Per uno spostamento permanente, passa 301 come codice di stato in modo che i motori di ricerca aggiornino il loro indice:

<?php

// 301 Moved Permanently
header("Location: https://example.com/new-page", true, 301);
exit;

Inviare un codice di stato personalizzato

Puoi impostare uno stato senza reindirizzare — per un'API che restituisce "not found", ad esempio:

<?php

header("HTTP/1.1 404 Not Found");
// or, more portably:
header("Status: 404 Not Found", true, 404);

echo "Resource not found";

Per i codici di stato in particolare, la funzione dedicata http_response_code() è più chiara e facile da leggere.

Forzare il download di un file

Combina Content-Type con Content-Disposition: attachment per far sì che il browser salvi il file invece di visualizzarlo:

<?php

$file = "report.pdf";

header("Content-Type: application/pdf");
header("Content-Disposition: attachment; filename=\"$file\"");
header("Content-Length: " . filesize($file));

readfile($file);   // stream the file to the client
exit;

Vedi readfile() per lo streaming del contenuto del file verso l'output.

Controllare la cache del browser

Gli header ti permettono di dire al browser se (e per quanto tempo) può riutilizzare una risposta:

<?php

// Tell the browser never to cache this response
header("Cache-Control: no-store, no-cache, must-revalidate");
header("Expires: 0");

Inviare più header con lo stesso nome

La maggior parte degli header sostituisce qualsiasi header precedente con lo stesso nome. Imposta il secondo argomento su false quando hai genuinamente bisogno di più di uno (raro, ma valido per alcuni header):

<?php

header("X-Sample: first");
header("X-Sample: second", false);   // both X-Sample headers are sent

Funzioni correlate

header() scrive un header alla volta, ma PHP ha helper di livello superiore per i casi più comuni:

• setcookie() e setrawcookie() — impostano un header Set-Cookie senza formattarlo manualmente. Vedi PHP Cookies.
• http_response_code() — legge o imposta il codice di stato.
• PHP Sessions — session_start() stesso invia header per i cookie, quindi ha lo stesso requisito "before output".

Per approfondire la definizione e la chiamata di funzioni personalizzate, vedi PHP Functions.

Conclusione

La funzione header() è la tua linea diretta verso gli header della risposta HTTP in PHP. Le regole sono semplici: costruisci la stringa dell'header, chiama header() prima di qualsiasi output, e usa exit dopo un redirect. Con essa puoi reindirizzare gli utenti, impostare i tipi di contenuto, servire download, inviare codici di stato e controllare la cache — i mattoni fondamentali di quasi ogni risposta PHP dinamica.

Pratica