xml_set_processing_instruction_handler()

La funzione xml_set_processing_instruction_handler() imposta una funzione definita dall'utente come handler per le istruzioni di elaborazione in un parser XML. Appartiene all'estensione legacy xml (Expat / SAX) e viene utilizzata con il parsing basato su eventi, non con la libreria SimpleXML. Ogni volta che il parser incontra un'istruzione di elaborazione nel documento, chiama il tuo handler in modo che tu possa reagire ad essa — ad esempio, per estrarre direttive incorporate o attivare un'azione durante il parsing.

Questa pagina tratta cosa sono le istruzioni di elaborazione, la sintassi e i parametri della funzione, un esempio completo e funzionante, la firma dell'handler, gli errori comuni e le alternative moderne a cui dovresti ricorrere oggi.

Avviso di deprecazione: L'estensione xml è stata deprecata in PHP 8.0 e completamente rimossa in PHP 8.2. Questa funzione è disponibile solo in PHP 7.4 e versioni precedenti. Per i progetti moderni, usa XMLReader o DOMDocument al suo posto.

Cos'è un'Istruzione di Elaborazione?

Un'istruzione di elaborazione (PI) è un nodo XML speciale che trasporta istruzioni specifiche dell'applicazione a qualsiasi software legga il documento. Non è contenuto di elementi — si trova tra il markup. Una PI ha due parti: un target (il nome subito dopo <?) e dei dati (tutto fino al ?> di chiusura):

<?target data ?>

Ad esempio, <?php-cache ttl="60" ?> ha il target php-cache e i dati ttl="60". La dichiarazione XML <?xml version="1.0"?> sembra una PI ma viene trattata in modo speciale e non attiva questo handler.

Sintassi

La sintassi della funzione xml_set_processing_instruction_handler() è la seguente:

xml_set_processing_instruction_handler($parser, $handler)

Dove $parser è la risorsa del parser XML restituita da xml_parser_create(), e $handler è un callable o una stringa contenente il nome della funzione definita dall'utente che gestirà le istruzioni di elaborazione. Passa una stringa vuota ("") per rimuovere un handler precedentemente registrato.

Parametri

Valore di Ritorno

Restituisce true in caso di successo, o false se $parser non è un parser XML valido.

La Firma dell'Handler

Il tuo handler viene chiamato con esattamente tre argomenti:

function handler($parser, string $target, string $data): void

• $parser — il parser che ha attivato il callback.
• $target — il target della PI (il nome immediatamente dopo <?).
• $data — il resto della PI, come stringa grezza. Sei responsabile di analizzarla tu stesso; il parser XML non la suddivide in attributi.

Esempi di Utilizzo

Vediamo un esempio pratico dell'utilizzo di xml_set_processing_instruction_handler() in PHP.

Esempio: Impostare una Funzione Handler per Istruzioni di Elaborazione

Supponiamo che tu abbia una stringa XML contenente istruzioni di elaborazione. Puoi usare la funzione xml_parser_create() per creare un nuovo parser XML, e poi impostare una funzione handler per le istruzioni di elaborazione usando xml_set_processing_instruction_handler(), in questo modo:

function handle_processing_instruction($parser, $target, $data) {
    echo "Processing instruction found: $target - $data\n";
}

$xml_parser = xml_parser_create();
xml_set_processing_instruction_handler($xml_parser, "handle_processing_instruction");

$xml_data = '<?xml version="1.0"?><root><?PI target data?></root>';
if (!xml_parse($xml_parser, $xml_data)) {
    echo "XML parse error: " . xml_error_string(xml_get_error_code($xml_parser));
}

xml_parser_free($xml_parser);

Questo codice crea un nuovo parser usando xml_parser_create(). Imposta poi una funzione personalizzata per gestire le istruzioni di elaborazione. La funzione xml_parse() elabora la stringa XML, attivando l'handler quando incontra un'istruzione di elaborazione. Il valore di ritorno viene verificato in modo che xml_error_string() possa segnalare eventuali errori di parsing. Infine, xml_parser_free() pulisce la risorsa del parser dopo l'uso.

Su PHP 7.4, il programma stampa:

Processing instruction found: PI - target data

Esempio: Analizzare i Dati delle PI in Opzioni

I dati delle PI arrivano come un'unica stringa grezza, quindi qualsiasi struttura al loro interno spetta a te analizzarla. Un pattern comune è trattare i dati come coppie key="value":

function pi_handler($parser, $target, $data) {
    // Pull out key="value" pairs from the PI data
    preg_match_all('/(\w+)="([^"]*)"/', $data, $pairs, PREG_SET_ORDER);
    $options = [];
    foreach ($pairs as $pair) {
        $options[$pair[1]] = $pair[2];
    }
    echo "Target: $target\n";
    print_r($options);
}

$parser = xml_parser_create();
xml_set_processing_instruction_handler($parser, "pi_handler");
xml_parse($parser, '<root><?cache ttl="60" scope="page"?></root>');
xml_parser_free($parser);

Su PHP 7.4, questo stampa:

Target: cache
Array
(
    [ttl] => 60
    [scope] => page
)

Handler Correlati

xml_set_processing_instruction_handler() è uno dei tanti setter di handler SAX. Di solito ne si registrano diversi insieme sullo stesso parser:

• xml_set_element_handler() — tag di apertura e chiusura.
• xml_set_character_data_handler() — testo tra i tag.
• xml_set_default_handler() — tutto ciò che nessun altro handler cattura.
• xml_set_object() — instrada gli handler ai metodi di un oggetto invece che a funzioni semplici.

Errori Comuni

• La dichiarazione XML non è una PI qui. <?xml ... ?> viene consumata dal parser e non raggiunge mai il tuo handler.
• I dati non sono analizzati. $data è una singola stringa. Il parser non suddividerà il contenuto key="value" in attributi per te — analizzali tu stesso.
• L'handler deve essere impostato prima del parsing. Registra l'handler prima di chiamare xml_parse(), altrimenti le istruzioni iniziali vengono perse.
• PHP 8.2+ non ha l'estensione xml. Tutte le funzioni xml_* sono scomparse; gli esempi in questa pagina funzionano solo su PHP 7.4 o versioni precedenti.

Conclusione

In questo articolo abbiamo discusso la funzione PHP xml_set_processing_instruction_handler() e come può essere utilizzata per impostare un handler per le istruzioni di elaborazione in un parser XML nell'estensione legacy xml. Ne abbiamo spiegato la sintassi e fornito un esempio pratico. Poiché l'estensione xml è stata rimossa in PHP 8.2, le applicazioni moderne dovrebbero preferire XMLReader o DOMDocument per l'elaborazione XML. Per i codici base legacy che girano su PHP 7.4 o versioni precedenti, questa funzione rimane un modo affidabile per gestire le istruzioni di elaborazione durante il parsing SAX.

Esercitazione