Função PHP http_response_code()

Toda resposta HTTP enviada por um servidor carrega um código de status — um número de três dígitos que informa ao navegador (ou cliente de API) se a requisição teve sucesso, foi redirecionada ou falhou. A função nativa http_response_code() do PHP, adicionada no PHP 5.4, permite ler ou definir esse código com uma única chamada. É a maneira mais simples e portável de retornar um 404 Not Found, um redirecionamento 301, um 403 Forbidden ou qualquer outro status a partir de um script PHP.

Este capítulo aborda a sintaxe, como obter versus definir o código atual, os códigos mais comuns que você utilizará, o problema com o buffer de saída que costuma confundir as pessoas e como http_response_code() se compara a definir a linha de status manualmente com header().

O que http_response_code() faz

http_response_code() tem dois modos, dependendo de você passar ou não um argumento:

• Modo de definição — http_response_code(404) define o código de status da resposta para 404.
• Modo de leitura — http_response_code() (sem argumento) retorna o código de status atual como um inteiro, ou false (em CLI retorna true/false) se nenhum código tiver sido definido ainda em um contexto web.

A função afeta apenas o código de status em si. Ela não envia um corpo, não redireciona o navegador nem exibe uma página de erro — isso ainda é responsabilidade sua.

Sintaxe

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

Valor de retorno: ao definir, retorna o código anterior (ou 200 se nenhum foi definido). Ao obter em contexto web, retorna o código atual. Fora de um servidor web (CLI), retorna true após definir e false ao ler sem código definido.

Definindo um código de status

O uso clássico é retornar uma resposta "não encontrado" a partir de um roteador ou de um handler de página inexistente:

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

O 404 é gravado no cabeçalho da resposta que é enviado antes do corpo, portanto o navegador sabe que a requisição falhou, mesmo que você ainda tenha impresso uma mensagem.

Um 403 para um recurso bloqueado funciona da mesma forma:

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

Lendo o código de status atual

Chame a função sem argumento para descobrir qual código a resposta carrega atualmente — útil em funções de encerramento, logs ou middleware:

<?php
http_response_code(404);

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

Redirecionando com um código de status

Um redirecionamento precisa de duas coisas: o código de status correto e um cabeçalho Location. Use http_response_code() para o código e header() para o destino:

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

Use 301 para uma movimentação permanente (os mecanismos de busca atualizam seu índice) e 302/307 para uma temporária.

Códigos de status HTTP mais comuns

O problema dos "cabeçalhos já enviados"

Os códigos de status ficam nos cabeçalhos HTTP, e os cabeçalhos devem ser enviados antes de qualquer saída. Se o seu script já exibiu HTML, imprimiu uma linha em branco ou possui espaço em branco antes da tag de abertura <?php, os cabeçalhos já foram enviados e http_response_code() não terá nenhum efeito (o PHP também emite um aviso de "headers already sent").

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

Para verificar se a saída já foi enviada, use headers_sent():

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

Soluções para as causas mais comuns: remova espaços em branco antes de <?php, evite echo/print antes de definir o código ou ative o buffer de saída com ob_start() para que a saída seja retida até você estar pronto.

http_response_code() vs. header()

Antes do PHP 5.4, era necessário construir a linha de status manualmente com 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() é preferível porque não exige que você codifique a versão HTTP ou o texto de status, e também pode ler o código atual — algo que uma chamada header() pura não consegue fazer. Consulte header() e headers_list() para um controle mais detalhado dos cabeçalhos de resposta.

Conclusão

http_response_code() é a forma mais limpa de ler ou definir um código de status HTTP no PHP. Lembre-se dos três pontos que importam na prática: chame-a antes de qualquer saída, escolha o código correto para a situação (404 para ausente, 403 para proibido, 301/302 para redirecionamentos) e combine redirecionamentos com um Location header(). Para se aprofundar nas ferramentas de requisição/resposta do PHP, explore as funções PHP e a função header().

Prática