Funzione PHP headers_list(): Tutto Quello che Devi Sapere

Ogni risposta PHP porta con sé un insieme di header HTTP — elementi come Content-Type, Set-Cookie e qualsiasi valore personalizzato che aggiungi. La funzione headers_list() ti consente di ispezionare quell'insieme dall'interno del tuo script: restituisce gli header che PHP sta per inviare (o ha già inviato) al client. Questo è prezioso per il debug di redirect, tipi di contenuto e cookie prima che la risposta venga inviata.

Questa pagina illustra cosa restituisce headers_list(), quando tali header sono effettivamente disponibili, la differenza tra essa e headers_sent(), e i modelli pratici per utilizzarla.

Sintassi

headers_list(): array

headers_list() non accetta nessun parametro e restituisce un array indicizzato di stringhe. Ogni stringa è una singola riga di header nella forma esatta in cui verrà inviata, ad esempio Content-Type: text/html; charset=UTF-8. Se non è stato impostato alcun header, viene restituito un array vuoto.

Un esempio di base

La funzione riflette qualsiasi header che PHP intende attualmente inviare. Impostane alcuni con header() prima, poi elencali:

<?php

header('Content-Type: application/json');
header('X-Powered-By: w3docs');

$headers = headers_list();
foreach ($headers as $header) {
    echo $header, "\n";
}

Un output tipico (l'insieme esatto dipende dalla tua configurazione PHP/server):

Content-Type: application/json
X-Powered-By: w3docs

PHP spesso aggiunge header predefiniti propri (come Content-Type e X-Powered-By) prima che il tuo codice venga eseguito, quindi l'elenco potrebbe contenere voci che non hai mai impostato esplicitamente.

Quando sono disponibili gli header?

headers_list() riflette solo gli header che PHP conserva nel suo buffer interno. Due conseguenze sono importanti:

• Riporta gli header indipendentemente dal fatto che siano stati inviati o meno. Usala insieme a headers_sent() quando hai bisogno di sapere se il buffer è già stato svuotato.
• Viene eseguita solo lato server. Non restituisce gli header di richiesta che il browser ti ha inviato — per quelli usa getallheaders() o il superglobale $_SERVER.

Verifica di un header specifico

Un'operazione comune consiste nel verificare che un particolare header sia stato impostato — ad esempio, confermando che il Location di un redirect sia presente prima di farci affidamento:

<?php

header('Location: /dashboard');

$hasLocation = false;
foreach (headers_list() as $header) {
    if (stripos($header, 'Location:') === 0) {
        $hasLocation = true;
        break;
    }
}

echo $hasLocation ? "Redirect header is set\n" : "No redirect header\n";

Output:

Redirect header is set

stripos(..., 'Location:') === 0 verifica la corrispondenza senza distinzione tra maiuscole e minuscole all'inizio della riga, poiché i nomi degli header non sono case-sensitive.

headers_list() vs. funzioni correlate

Poiché headers_list() è di sola lettura, è sicuro chiamarla in qualsiasi momento — non produce mai l'avviso "headers already sent" che può generare header().

Casi d'uso comuni

• Debug: scarica headers_list() durante lo sviluppo per vedere esattamente cosa sta inviando il server, inclusi i cookie impostati da setcookie().
• Logica condizionale: decidi se aggiungere un header solo se non è già presente.
• Testing: verifica che un controller abbia prodotto il Content-Type o il Cache-Control attesi.

Conclusione

headers_list() fornisce uno snapshot di sola lettura degli header di risposta HTTP che PHP intende inviare. Abbinala a headers_sent() per controllare i tempi, header() per impostare i valori, e header_remove() per eliminarli. Insieme, queste funzioni ti danno il pieno controllo sull'intestazione della risposta prima che raggiunga il browser.

Esercizio