PHP header_register_callback() Function

As a PHP developer, you may need to manipulate HTTP headers dynamically in your web application. The header_register_callback() function is a built-in PHP tool that registers a callback to execute automatically when headers are about to be sent to the client. This guide covers its syntax, usage, and best practices.

What is the header_register_callback() Function?

The header_register_callback() function registers a callback that PHP runs at the last moment before HTTP headers are flushed to the client. This gives you a single, guaranteed hook to inspect or finalize the response headers right before they leave the server — for example, to add a header that depends on the response body, or to strip a header that an earlier part of the request set.

It pairs naturally with header(), which sets a raw header, and headers_list(), which lets you read the headers queued so far. Because the callback fires before the headers are committed, you can still safely call header() or header_remove() from inside it — something you cannot do once output has already been sent.

When Would You Use It?

Use header_register_callback() when you need to set or change a header based on information that is only known after the request logic has run, such as:

• Adding a Content-Length or checksum header computed from buffered output.
• Setting a security header (for example Content-Security-Policy) in one central place instead of scattering header() calls throughout the code.
• Removing a header (like X-Powered-By) that a library added earlier in the request.

How to Use the header_register_callback() Function

Using the header_register_callback() function is straightforward. Here is the syntax of the function:

The PHP syntax of header_register_callback() Function

header_register_callback(callable $callback): bool

The function takes one parameter:

• callback: A callable function with no parameters that you want to register.

Note: Available since PHP 5.4.0. Returns true on success, or false on failure. Always check the return value to ensure the callback was registered correctly.

Here is an example of how to use the header_register_callback() function to register a callback function:

How to Use the header_register_callback() Function?

<?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');
}

In this example, we define a callback function called my_callback that accepts no parameters. We then register this callback function using the header_register_callback() function. The callback is invoked exactly once when headers are about to be sent to the client, allowing you to modify or add HTTP headers using the header() function.

Compatibility Note: The callback executes during the request shutdown phase. If you use output buffering (ob_start()) or register_shutdown_function(), be aware that this callback runs after output is flushed but before the script fully terminates. This timing makes it safe for setting headers based on runtime conditions without interfering with early output.

A Practical Example

A common use is centralizing security headers and reading back what is already queued. Inside the callback you can use headers_list() to see the current headers and conditionally adjust them:

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

Because the callback fires once, right before the headers are committed, every response from this script gets X-Content-Type-Options: nosniff and never leaks X-Powered-By, regardless of what the rest of the request did.

Gotcha: A callback can only be registered before headers are sent. If output has already started (so headers_sent() returns true), the callback will never run. Register it early — ideally before any echo or HTML output.

Conclusion

The header_register_callback() function provides a reliable way to modify HTTP headers dynamically. By checking its return value and understanding its execution timing, you can safely integrate it into your PHP applications.

Practice