Função PHP header_register_callback()

Como desenvolvedor PHP, pode ser necessário manipular cabeçalhos HTTP dinamicamente em sua aplicação web. A função header_register_callback() é uma ferramenta PHP nativa que registra um callback para ser executado automaticamente quando os cabeçalhos estão prestes a ser enviados ao cliente. Este guia aborda sua sintaxe, uso e boas práticas.

O que é a Função header_register_callback()?

A função header_register_callback() registra um callback que o PHP executa no último momento antes de os cabeçalhos HTTP serem enviados ao cliente. Isso fornece um ponto de interceptação único e garantido para inspecionar ou finalizar os cabeçalhos da resposta antes que eles saiam do servidor — por exemplo, para adicionar um cabeçalho que dependa do corpo da resposta, ou para remover um cabeçalho definido por uma parte anterior da requisição.

Ela combina naturalmente com header(), que define um cabeçalho bruto, e headers_list(), que permite ler os cabeçalhos na fila até o momento. Como o callback é acionado antes de os cabeçalhos serem confirmados, ainda é possível chamar header() ou header_remove() a partir dele — algo que não é possível fazer depois que a saída já foi enviada.

Quando Usá-la?

Use header_register_callback() quando precisar definir ou alterar um cabeçalho com base em informações que só são conhecidas após a execução da lógica da requisição, como:

• Adicionar um cabeçalho Content-Length ou de checksum calculado a partir da saída em buffer.
• Definir um cabeçalho de segurança (por exemplo, Content-Security-Policy) em um único lugar centralizado, em vez de espalhar chamadas header() por todo o código.
• Remover um cabeçalho (como X-Powered-By) que uma biblioteca adicionou anteriormente na requisição.

Como Usar a Função header_register_callback()

O uso da função header_register_callback() é simples. Veja a sintaxe da função:

Sintaxe PHP da Função header_register_callback()

header_register_callback(callable $callback): bool

A função aceita um parâmetro:

• callback: Uma função callable sem parâmetros que você deseja registrar.

Nota: Disponível desde o PHP 5.4.0. Retorna true em caso de sucesso, ou false em caso de falha. Sempre verifique o valor de retorno para garantir que o callback foi registrado corretamente.

Veja um exemplo de como usar a função header_register_callback() para registrar uma função de callback:

Como Usar a Função 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');
}

Neste exemplo, definimos uma função de callback chamada my_callback que não aceita parâmetros. Em seguida, registramos essa função usando header_register_callback(). O callback é invocado exatamente uma vez quando os cabeçalhos estão prestes a ser enviados ao cliente, permitindo modificar ou adicionar cabeçalhos HTTP com a função header().

Nota de compatibilidade: O callback é executado durante a fase de encerramento da requisição. Se você usar buffer de saída (ob_start()) ou register_shutdown_function(), saiba que este callback é executado após a saída ser descarregada, mas antes do término completo do script. Esse momento o torna seguro para definir cabeçalhos com base em condições de tempo de execução sem interferir na saída antecipada.

Um Exemplo Prático

Um uso comum é centralizar cabeçalhos de segurança e ler o que já está na fila. Dentro do callback, você pode usar headers_list() para ver os cabeçalhos atuais e ajustá-los 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!';

Como o callback é acionado uma única vez, logo antes de os cabeçalhos serem confirmados, todas as respostas deste script recebem X-Content-Type-Options: nosniff e nunca expõem X-Powered-By, independentemente do que o restante da requisição tenha feito.

Atenção: Um callback só pode ser registrado antes que os cabeçalhos sejam enviados. Se a saída já tiver começado (ou seja, se headers_sent() retornar true), o callback nunca será executado. Registre-o cedo — idealmente antes de qualquer echo ou saída HTML.

Conclusão

A função header_register_callback() oferece uma maneira confiável de modificar cabeçalhos HTTP dinamicamente. Ao verificar seu valor de retorno e compreender o momento de sua execução, você pode integrá-la com segurança em suas aplicações PHP.

Practice