Fonction PHP http_response_code()

Chaque réponse HTTP envoyée par un serveur contient un code de statut — un nombre à trois chiffres qui indique au navigateur (ou au client API) si la requête a réussi, a été redirigée ou a échoué. La fonction intégrée http_response_code() de PHP, ajoutée en PHP 5.4, vous permet de lire ou de définir ce code en un seul appel. C'est la façon la plus simple et la plus portable de retourner un 404 Not Found, une redirection 301, un 403 Forbidden ou tout autre statut depuis un script PHP.

Ce chapitre couvre la syntaxe, la différence entre obtenir et définir le code courant, les codes les plus fréquemment utilisés, le piège lié à la mise en tampon de sortie, et comment http_response_code() se compare à la définition manuelle de la ligne de statut avec header().

Ce que fait http_response_code()

http_response_code() fonctionne selon deux modes en fonction de la présence ou non d'un argument :

• Mode définition — http_response_code(404) définit le code de statut de la réponse à 404.
• Mode lecture — http_response_code() (sans argument) retourne le code de statut courant sous forme d'entier, ou false (en CLI, il retourne true/false) si aucun code n'a encore été défini dans un contexte web.

Il ne touche qu'au code de statut lui-même. Il n'envoie pas de corps, ne redirige pas le navigateur et n'affiche pas de page d'erreur — cela reste votre responsabilité.

Syntaxe

http_response_code(int $response_code = null): int|bool

Valeur de retour : lors de la définition, la fonction retourne le code précédent (ou 200 si aucun n'était défini). En mode lecture dans un contexte web, elle retourne le code courant. En dehors d'un serveur web (CLI), elle retourne true après avoir défini un code et false en lecture si aucun code n'est défini.

Définir un code de statut

L'utilisation classique consiste à retourner une réponse « introuvable » depuis un routeur ou un gestionnaire de page manquante :

<?php
// Tell the client this page does not exist
http_response_code(404);
echo "Page not found.";

Le 404 est écrit dans l'en-tête de réponse qui part avant le corps, de sorte que le navigateur sait que la requête a échoué même si vous avez quand même affiché un message.

Un 403 pour une ressource bloquée fonctionne de la même manière :

<?php
if (!$userIsLoggedIn) {
    http_response_code(403);
    exit("Access denied.");
}

Lire le code de statut courant

Appelez la fonction sans argument pour connaître le code que porte actuellement la réponse — utile dans les fonctions de fermeture, la journalisation ou les intergiciels :

<?php
http_response_code(404);

// Later in the same request:
$current = http_response_code();
echo $current; // 404

Rediriger avec un code de statut

Une redirection nécessite deux choses : le bon code de statut et un en-tête Location. Utilisez http_response_code() pour le code et header() pour la destination :

<?php
// Permanent redirect to the new URL
http_response_code(301);
header("Location: https://www.w3docs.com/new-page");
exit;

Utilisez 301 pour un déplacement permanent (les moteurs de recherche mettent à jour leur index) et 302/307 pour un déplacement temporaire.

Codes de statut HTTP courants

Le piège des « en-têtes déjà envoyés »

Les codes de statut font partie des en-têtes HTTP, et les en-têtes doivent être envoyés avant tout contenu. Si votre script a déjà affiché du HTML, imprimé une ligne vide, ou même contient des espaces avant la balise d'ouverture <?php, les en-têtes sont déjà envoyés et http_response_code() ne fait rien en silence (PHP émet également un avertissement « headers already sent »).

<?php
echo "Hello";          // body sent → headers are now locked
http_response_code(404); // too late, has no effect

Pour vérifier si la sortie a déjà été envoyée, utilisez headers_sent() :

<?php
if (!headers_sent()) {
    http_response_code(404);
}

Solutions pour les causes courantes : supprimez les espaces parasites avant <?php, évitez echo/print avant de définir le code, ou activez la mise en tampon de sortie avec ob_start() pour retenir la sortie jusqu'au moment opportun.

http_response_code() vs. header()

Avant PHP 5.4, il fallait construire manuellement la ligne de statut avec header() :

<?php
// The old way — still works, but verbose and you must repeat the protocol/text
header("HTTP/1.1 404 Not Found");

// The modern equivalent
http_response_code(404);

http_response_code() est préférable car elle ne nécessite pas de coder en dur la version HTTP ou le texte de statut, et elle peut également lire le code courant — ce qu'un appel brut à header() ne peut pas faire. Consultez header() et headers_list() pour un contrôle plus fin des en-têtes de réponse.

Conclusion

http_response_code() est la façon la plus propre de lire ou de définir un code de statut HTTP en PHP. Retenez les trois points essentiels en pratique : appelez-la avant tout contenu, choisissez le bon code selon la situation (404 pour introuvable, 403 pour interdit, 301/302 pour les redirections), et associez les redirections à un en-tête Location via header(). Pour approfondir les outils requête/réponse de PHP, explorez les fonctions PHP et la fonction header().

Pratique