Функция PHP header_register_callback()

Как PHP-разработчику, вам может потребоваться динамически управлять HTTP-заголовками в веб-приложении. Функция header_register_callback() — это встроенный инструмент PHP, который регистрирует обратный вызов для автоматического выполнения в момент, когда заголовки готовы к отправке клиенту. В этом руководстве рассматриваются синтаксис, использование и рекомендации по применению функции.

Что такое функция header_register_callback()?

Функция header_register_callback() регистрирует обратный вызов, который PHP выполняет в последний момент перед тем, как HTTP-заголовки будут отправлены клиенту. Это даёт вам единственный гарантированный перехватчик для проверки или финализации заголовков ответа непосредственно перед их отправкой с сервера — например, чтобы добавить заголовок, зависящий от тела ответа, или удалить заголовок, установленный на более раннем этапе обработки запроса.

Она хорошо сочетается с header(), которая устанавливает «сырой» заголовок, и headers_list(), которая позволяет прочитать уже поставленные в очередь заголовки. Поскольку обратный вызов срабатывает до фиксации заголовков, внутри него по-прежнему можно безопасно вызывать header() или header_remove() — чего нельзя сделать после того, как вывод уже был отправлен.

Когда это нужно использовать?

Используйте header_register_callback(), когда необходимо установить или изменить заголовок на основе информации, которая становится известна только после выполнения логики запроса, например:

• Добавление заголовка Content-Length или контрольной суммы, вычисленной из буферизованного вывода.
• Установка заголовка безопасности (например, Content-Security-Policy) в одном центральном месте вместо разбросанных по коду вызовов header().
• Удаление заголовка (например, X-Powered-By), добавленного библиотекой на более раннем этапе запроса.

Как использовать функцию header_register_callback()

Использование функции header_register_callback() довольно просто. Вот синтаксис функции:

Синтаксис PHP функции header_register_callback()

header_register_callback(callable $callback): bool

Функция принимает один параметр:

• callback: Вызываемая функция без параметров, которую вы хотите зарегистрировать.

Примечание: Доступно начиная с PHP 5.4.0. Возвращает true при успехе или false при ошибке. Всегда проверяйте возвращаемое значение, чтобы убедиться, что обратный вызов был зарегистрирован корректно.

Вот пример использования функции header_register_callback() для регистрации функции обратного вызова:

Как использовать функцию header_register_callback()?

<?php

function my_callback() {
    header('X-Custom-Header: CustomValue');
}

if (!header_register_callback('my_callback')) {
    // Handle potential registration failure
    error_log('Failed to register header callback');
}

В этом примере мы определяем функцию обратного вызова my_callback, которая не принимает параметров. Затем мы регистрируем эту функцию с помощью header_register_callback(). Обратный вызов выполняется ровно один раз в момент, когда заголовки готовы к отправке клиенту, что позволяет изменять или добавлять HTTP-заголовки с помощью функции header().

Примечание о совместимости: Обратный вызов выполняется на этапе завершения запроса. Если вы используете буферизацию вывода (ob_start()) или register_shutdown_function(), учтите, что этот обратный вызов выполняется после сброса вывода, но до полного завершения скрипта. Такое время выполнения делает его безопасным для установки заголовков на основе условий времени выполнения без вмешательства в ранний вывод.

Практический пример

Распространённый вариант использования — централизация заголовков безопасности и чтение уже поставленных в очередь заголовков. Внутри обратного вызова вы можете использовать headers_list(), чтобы просмотреть текущие заголовки и при необходимости скорректировать их:

<?php

function finalize_headers() {
    // Add a security header for every response.
    header('X-Content-Type-Options: nosniff');

    // Remove a header earlier code may have set.
    header_remove('X-Powered-By');

    // Inspect what is about to be sent.
    foreach (headers_list() as $h) {
        error_log('Outgoing header: ' . $h);
    }
}

header_register_callback('finalize_headers');

echo 'Hello, world!';

Поскольку обратный вызов срабатывает один раз, непосредственно перед фиксацией заголовков, каждый ответ этого скрипта будет содержать X-Content-Type-Options: nosniff и никогда не раскроет X-Powered-By, независимо от того, что делал остальной код запроса.

Важно: Обратный вызов можно зарегистрировать только до отправки заголовков. Если вывод уже начался (то есть headers_sent() возвращает true), обратный вызов никогда не выполнится. Регистрируйте его как можно раньше — в идеале до любого echo или HTML-вывода.

Заключение

Функция header_register_callback() предоставляет надёжный способ динамического изменения HTTP-заголовков. Проверяя возвращаемое значение и понимая время выполнения, вы можете безопасно интегрировать её в свои PHP-приложения.

Практика