Funzione PHP header_register_callback()

Come sviluppatore PHP, potresti dover manipolare gli header HTTP dinamicamente nella tua applicazione web. La funzione header_register_callback() è uno strumento integrato di PHP che registra una callback da eseguire automaticamente quando gli header stanno per essere inviati al client. Questa guida ne descrive la sintassi, l'utilizzo e le best practice.

Cos'è la funzione header_register_callback()?

La funzione header_register_callback() registra una callback che PHP esegue nell'ultimo momento prima che gli header HTTP vengano inviati al client. Questo ti fornisce un unico punto di aggancio garantito per ispezionare o finalizzare gli header di risposta appena prima che lascino il server — ad esempio, per aggiungere un header che dipende dal corpo della risposta, o per rimuovere un header impostato in una fase precedente della richiesta.

Si abbina naturalmente a header(), che imposta un header raw, e a headers_list(), che permette di leggere gli header attualmente in coda. Poiché la callback si attiva prima che gli header vengano inviati definitivamente, è ancora possibile chiamare header() o header_remove() dall'interno di essa — cosa che non è possibile fare una volta che l'output è già stato inviato.

Quando si usa?

Usa header_register_callback() quando hai bisogno di impostare o modificare un header in base a informazioni note solo dopo l'esecuzione della logica della richiesta, ad esempio:

• Aggiungere un header Content-Length o di checksum calcolato dall'output bufferizzato.
• Impostare un header di sicurezza (ad esempio Content-Security-Policy) in un unico punto centralizzato anziché distribuire le chiamate header() in tutto il codice.
• Rimuovere un header (come X-Powered-By) aggiunto in precedenza da una libreria durante la richiesta.

Come usare la funzione header_register_callback()

Utilizzare la funzione header_register_callback() è semplice. Ecco la sintassi della funzione:

Sintassi PHP della funzione header_register_callback()

header_register_callback(callable $callback): bool

La funzione accetta un parametro:

• callback: Una funzione callable senza parametri che si desidera registrare.

Nota: Disponibile da PHP 5.4.0. Restituisce true in caso di successo, o false in caso di errore. Controlla sempre il valore restituito per assicurarti che la callback sia stata registrata correttamente.

Ecco un esempio di come utilizzare la funzione header_register_callback() per registrare una funzione di callback:

Come usare la funzione 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');
}

In questo esempio, definiamo una funzione di callback chiamata my_callback che non accetta parametri. Registriamo quindi questa funzione di callback usando la funzione header_register_callback(). La callback viene invocata esattamente una volta quando gli header stanno per essere inviati al client, permettendoti di modificare o aggiungere header HTTP usando la funzione header().

Nota sulla compatibilità: La callback viene eseguita durante la fase di shutdown della richiesta. Se utilizzi il buffering dell'output (ob_start()) o register_shutdown_function(), tieni presente che questa callback viene eseguita dopo che l'output è stato inviato ma prima che lo script termini completamente. Questa tempistica la rende sicura per impostare gli header in base alle condizioni di runtime senza interferire con l'output anticipato.

Un esempio pratico

Un utilizzo comune è la centralizzazione degli header di sicurezza e la lettura di quelli già in coda. All'interno della callback puoi usare headers_list() per vedere gli header correnti e modificarli in modo condizionale:

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

Poiché la callback si attiva una sola volta, appena prima che gli header vengano inviati definitivamente, ogni risposta di questo script riceve X-Content-Type-Options: nosniff e non espone mai X-Powered-By, indipendentemente da ciò che ha fatto il resto della richiesta.

Attenzione: Una callback può essere registrata solo prima che gli header vengano inviati. Se l'output è già iniziato (quindi headers_sent() restituisce true), la callback non verrà mai eseguita. Registrala presto — idealmente prima di qualsiasi echo o output HTML.

Conclusione

La funzione header_register_callback() offre un modo affidabile per modificare gli header HTTP dinamicamente. Controllando il suo valore di ritorno e comprendendo i tempi di esecuzione, puoi integrarla in modo sicuro nelle tue applicazioni PHP.

Practice