Función PHP header_register_callback()

Como desarrollador PHP, es posible que necesites manipular cabeceras HTTP de forma dinámica en tu aplicación web. La función header_register_callback() es una herramienta integrada de PHP que registra un callback para ejecutarse automáticamente justo antes de que las cabeceras se envíen al cliente. Esta guía cubre su sintaxis, uso y mejores prácticas.

¿Qué es la función header_register_callback()?

La función header_register_callback() registra un callback que PHP ejecuta en el último momento antes de que las cabeceras HTTP se envíen al cliente. Esto te proporciona un único punto garantizado para inspeccionar o finalizar las cabeceras de respuesta justo antes de que salgan del servidor — por ejemplo, para añadir una cabecera que depende del cuerpo de la respuesta, o para eliminar una cabecera que una parte anterior de la solicitud estableció.

Se combina de forma natural con header(), que establece una cabecera sin procesar, y con headers_list(), que permite leer las cabeceras en cola hasta ese momento. Como el callback se ejecuta antes de que las cabeceras se confirmen, aún puedes llamar a header() o a header_remove() desde dentro — algo que no puedes hacer una vez que la salida ya ha sido enviada.

¿Cuándo deberías usarla?

Usa header_register_callback() cuando necesites establecer o cambiar una cabecera en función de información que solo se conoce después de que la lógica de la solicitud haya finalizado, como:

• Añadir una cabecera Content-Length o de suma de verificación calculada a partir de la salida almacenada en búfer.
• Establecer una cabecera de seguridad (por ejemplo, Content-Security-Policy) en un lugar centralizado en lugar de dispersar llamadas a header() por todo el código.
• Eliminar una cabecera (como X-Powered-By) que una biblioteca añadió anteriormente en la solicitud.

Cómo usar la función header_register_callback()

Usar la función header_register_callback() es sencillo. Aquí está la sintaxis de la función:

Sintaxis PHP de la función header_register_callback()

header_register_callback(callable $callback): bool

La función acepta un parámetro:

• callback: Una función callable sin parámetros que deseas registrar.

Nota: Disponible desde PHP 5.4.0. Devuelve true en caso de éxito, o false en caso de error. Comprueba siempre el valor de retorno para asegurarte de que el callback se registró correctamente.

A continuación se muestra un ejemplo de cómo usar la función header_register_callback() para registrar una función callback:

¿Cómo usar la función 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');
}

En este ejemplo, definimos una función callback llamada my_callback que no acepta parámetros. Luego registramos esta función callback usando la función header_register_callback(). El callback se invoca exactamente una vez cuando las cabeceras están a punto de enviarse al cliente, permitiéndote modificar o añadir cabeceras HTTP usando la función header().

Nota de compatibilidad: El callback se ejecuta durante la fase de cierre de la solicitud. Si usas el almacenamiento en búfer de salida (ob_start()) o register_shutdown_function(), ten en cuenta que este callback se ejecuta después de que la salida se vacía, pero antes de que el script termine completamente. Este momento lo hace seguro para establecer cabeceras basadas en condiciones de tiempo de ejecución sin interferir con la salida temprana.

Un ejemplo práctico

Un uso común es centralizar las cabeceras de seguridad y leer lo que ya está en cola. Dentro del callback puedes usar headers_list() para ver las cabeceras actuales y ajustarlas condicionalmente:

<?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!';

Dado que el callback se ejecuta una sola vez, justo antes de que las cabeceras se confirmen, cada respuesta de este script obtiene X-Content-Type-Options: nosniff y nunca expone X-Powered-By, independientemente de lo que haya hecho el resto de la solicitud.

Advertencia: Un callback solo puede registrarse antes de que se envíen las cabeceras. Si la salida ya ha comenzado (es decir, headers_sent() devuelve true), el callback nunca se ejecutará. Regístralo pronto — idealmente antes de cualquier echo o salida HTML.

Conclusión

La función header_register_callback() proporciona una forma fiable de modificar cabeceras HTTP de forma dinámica. Al comprobar su valor de retorno y entender su momento de ejecución, puedes integrarlo de forma segura en tus aplicaciones PHP.

Práctica