Функция PHP http_response_code()

Каждый HTTP-ответ сервера содержит код состояния — трёхзначное число, сообщающее браузеру (или API-клиенту), был ли запрос выполнен успешно, перенаправлен или завершился ошибкой. Встроенная функция PHP http_response_code(), добавленная в PHP 5.4, позволяет прочитать или задать этот код одним вызовом. Это самый простой и переносимый способ вернуть 404 Not Found, редирект 301, 403 Forbidden или любой другой статус из PHP-скрипта.

В этой главе рассматриваются синтаксис функции, различия между режимами получения и установки кода, наиболее распространённые коды, ловушка с буферизацией вывода, а также сравнение http_response_code() с ручной установкой строки статуса через header().

Что делает http_response_code()

http_response_code() работает в двух режимах в зависимости от того, передан ли аргумент:

• Режим установки — http_response_code(404) устанавливает код ответа 404.
• Режим получения — http_response_code() (без аргумента) возвращает текущий код состояния в виде целого числа или false (в CLI возвращает true/false), если код ещё не задан в веб-контексте.

Функция затрагивает только сам код состояния. Она не отправляет тело ответа, не перенаправляет браузер и не выводит страницу с ошибкой — это по-прежнему ваша задача.

Синтаксис

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

Возвращаемое значение: при установке возвращает предыдущий код (или 200, если ни один не был задан). При получении в веб-контексте возвращает текущий код. Вне веб-сервера (CLI) возвращает true после установки и false при чтении без заданного кода.

Установка кода состояния

Классический вариант использования — возврат ответа «не найдено» из маршрутизатора или обработчика отсутствующей страницы:

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

Код 404 записывается в заголовок ответа, который отправляется до тела, поэтому браузер знает, что запрос не выполнен, даже если вы вывели сообщение.

Для заблокированного ресурса код 403 выглядит аналогично:

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

Чтение текущего кода состояния

Вызовите функцию без аргумента, чтобы узнать текущий код ответа — это удобно в функциях завершения, логировании или промежуточном программном обеспечении:

<?php
http_response_code(404);

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

Редирект с кодом состояния

Для редиректа нужны две вещи: правильный код состояния и заголовок Location. Используйте http_response_code() для кода и header() для адреса назначения:

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

Используйте 301 для постоянного перемещения (поисковые системы обновят индекс) и 302/307 для временного.

Распространённые HTTP-коды состояния

Ловушка «заголовки уже отправлены»

Коды состояния передаются в HTTP-заголовках, а заголовки должны быть отправлены до любого вывода. Если скрипт уже вывел HTML, напечатал пустую строку или даже содержит пробел перед открывающим тегом <?php, заголовки уже сброшены и http_response_code() не сделает ничего (PHP также выдаёт предупреждение «headers already sent»).

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

Чтобы проверить, был ли уже начат вывод, используйте headers_sent():

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

Решения для распространённых причин: удалите лишние пробелы перед <?php, избегайте echo/print до установки кода или включите буферизацию вывода с помощью ob_start(), чтобы вывод задерживался до нужного момента.

http_response_code() vs. header()

До PHP 5.4 строку статуса приходилось формировать вручную с помощью 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() предпочтительнее, поскольку не требует жёсткого задания версии HTTP или текста статуса и позволяет читать текущий код — чего не умеет сырой вызов header(). Для более тонкого управления заголовками ответа смотрите header() и headers_list().

Заключение

http_response_code() — самый чистый способ читать или задавать HTTP-код состояния в PHP. Запомните три важных момента: вызывайте функцию до любого вывода, выбирайте правильный код для конкретной ситуации (404 для отсутствующих ресурсов, 403 для запрещённых, 301/302 для редиректов), и сопровождайте редиректы заголовком Location через header(). Для более глубокого изучения инструментов запросов/ответов PHP ознакомьтесь с функциями PHP и функцией header().

Практика