Fonction PHP headers_list() : Tout ce que vous devez savoir

Chaque réponse PHP transporte un ensemble d'en-têtes HTTP — comme Content-Type, Set-Cookie, et toutes les valeurs personnalisées que vous ajoutez. La fonction headers_list() vous permet d'inspecter cet ensemble depuis l'intérieur de votre script : elle retourne les en-têtes que PHP s'apprête à envoyer (ou a déjà envoyés) au client. C'est une ressource précieuse pour déboguer les redirections, les types de contenu et les cookies avant que la réponse ne soit transmise.

Cette page explique ce que retourne headers_list(), à quel moment ces en-têtes existent réellement, la différence entre cette fonction et headers_sent(), ainsi que des modèles pratiques d'utilisation.

Syntaxe

headers_list(): array

headers_list() ne prend aucun paramètre et retourne un array indexé de chaînes de caractères. Chaque chaîne correspond à une ligne d'en-tête unique dans la forme exacte où elle sera envoyée, par exemple Content-Type: text/html; charset=UTF-8. Si aucun en-tête n'a encore été défini, vous obtenez un tableau vide.

Un exemple de base

La fonction reflète les en-têtes que PHP prévoit actuellement d'envoyer. Définissez-en quelques-uns avec header() d'abord, puis listez-les :

<?php

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

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

Un exemple de sortie typique (l'ensemble exact dépend de votre configuration PHP/serveur) :

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

PHP ajoute souvent des en-têtes par défaut (comme Content-Type et X-Powered-By) avant l'exécution de votre code, de sorte que la liste peut contenir des entrées que vous n'avez jamais définies explicitement.

Quand les en-têtes sont-ils disponibles ?

headers_list() ne reflète que les en-têtes que PHP conserve dans son tampon interne. Deux conséquences importantes :

• Elle signale les en-têtes qu'ils aient été envoyés ou non. Utilisez-la conjointement avec headers_sent() lorsque vous avez besoin de savoir si le tampon a déjà été vidé.
• Elle s'exécute côté serveur uniquement. Elle ne retourne pas les en-têtes de requête que le navigateur vous a envoyés — pour cela, utilisez getallheaders() ou la superglobale $_SERVER.

Vérifier un en-tête spécifique

Une tâche courante consiste à vérifier qu'un en-tête particulier a été défini — par exemple, confirmer que le Location d'une redirection est présent avant de s'y fier :

<?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";

Sortie :

Redirect header is set

stripos(..., 'Location:') === 0 correspond de manière insensible à la casse au début de la ligne, car les noms d'en-têtes ne sont pas sensibles à la casse.

headers_list() par rapport aux fonctions associées

Comme headers_list() est en lecture seule, elle peut être appelée à n'importe quel moment en toute sécurité — elle ne produit jamais l'avertissement "headers already sent" que peut générer header().

Cas d'utilisation courants

• Débogage : videz headers_list() pendant le développement pour voir exactement ce que le serveur envoie, y compris les cookies définis par setcookie().
• Logique conditionnelle : décidez d'ajouter un en-tête uniquement s'il n'est pas déjà présent.
• Tests : vérifiez qu'un contrôleur a produit le Content-Type ou le Cache-Control attendu.

Conclusion

headers_list() vous fournit un instantané en lecture seule des en-têtes de réponse HTTP que PHP prévoit d'envoyer. Combinez-la avec headers_sent() pour vérifier le timing, header() pour définir des valeurs, et header_remove() pour les effacer. Ensemble, ces fonctions vous donnent un contrôle total sur l'en-tête de réponse avant qu'il n'atteigne le navigateur.

Pratique