Funzione PHP http_response_code()

Ogni risposta HTTP inviata da un server include un codice di stato — un numero a tre cifre che indica al browser (o al client API) se la richiesta è riuscita, è stata reindirizzata o ha avuto un errore. La funzione built-in di PHP http_response_code(), introdotta in PHP 5.4, permette di leggere o impostare quel codice con una singola chiamata. È il modo più semplice e portabile per restituire un 404 Not Found, un redirect 301, un 403 Forbidden o qualsiasi altro stato da uno script PHP.

Questo capitolo illustra la sintassi, come ottenere vs. impostare il codice corrente, i codici più comuni, il problema del buffering dell'output che sorprende molti sviluppatori, e come http_response_code() si confronta con l'impostazione manuale della riga di stato tramite header().

Cosa fa http_response_code()

http_response_code() ha due modalità a seconda che si passi o meno un argomento:

• Modalità impostazione — http_response_code(404) imposta il codice di stato della risposta a 404.
• Modalità lettura — http_response_code() (senza argomento) restituisce il codice di stato corrente come intero, oppure false (in CLI restituisce true/false) se nessun codice è ancora stato impostato in un contesto web.

Agisce solo sul codice di stato. Non invia un corpo, non reindirizza il browser e non mostra una pagina di errore — quello rimane compito tuo.

Sintassi

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

Valore di ritorno: in modalità impostazione, restituisce il codice precedente (o 200 se non ne era stato impostato nessuno). In modalità lettura in un contesto web, restituisce il codice corrente. Al di fuori di un server web (CLI), restituisce true dopo l'impostazione e false in lettura senza codice impostato.

Impostare un codice di stato

L'uso classico è restituire una risposta "non trovato" da un router o da un gestore di pagine mancanti:

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

Il 404 viene scritto nell'header della risposta che viene inviato prima del corpo, quindi il browser sa che la richiesta è fallita anche se hai comunque stampato un messaggio.

Un 403 per una risorsa bloccata funziona allo stesso modo:

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

Leggere il codice di stato corrente

Chiama la funzione senza argomenti per scoprire quale codice porta attualmente la risposta — utile in funzioni di shutdown, logging o middleware:

<?php
http_response_code(404);

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

Reindirizzare con un codice di stato

Un redirect richiede due cose: il codice di stato corretto e un header Location. Usa http_response_code() per il codice e header() per la destinazione:

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

Usa 301 per uno spostamento permanente (i motori di ricerca aggiornano il loro indice) e 302/307 per uno temporaneo.

Codici di stato HTTP comuni

Il problema degli "header già inviati"

I codici di stato si trovano negli header HTTP, e gli header devono essere inviati prima di qualsiasi output. Se lo script ha già stampato HTML, una riga vuota o persino degli spazi prima del tag di apertura <?php, gli header sono già stati inviati e http_response_code() non fa nulla in silenzio (PHP emette anche un avviso "headers already sent").

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

Per verificare se l'output è già stato inviato, usa headers_sent():

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

Le soluzioni alle cause più comuni: rimuovi gli spazi indesiderati prima di <?php, evita echo/print prima di impostare il codice, oppure abilita il buffering dell'output con ob_start() in modo che l'output venga trattenuto finché non sei pronto.

http_response_code() vs. header()

Prima di PHP 5.4 era necessario costruire manualmente la riga di stato con 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() è preferibile perché non richiede di codificare in modo fisso la versione HTTP o il testo di stato, e può anche leggere il codice corrente — cosa che una chiamata raw a header() non può fare. Vedi header() e headers_list() per un controllo più preciso degli header di risposta.

Conclusione

http_response_code() è il modo più pulito per leggere o impostare un codice di stato HTTP in PHP. Ricorda le tre cose che contano in pratica: chiamala prima di qualsiasi output, scegli il codice giusto per la situazione (404 per le risorse mancanti, 403 per quelle vietate, 301/302 per i redirect), e abbina i redirect a un Location tramite header(). Per approfondire gli strumenti PHP di request/response, esplora le funzioni PHP e la funzione header().

Pratica