xml_parser_free()

La funzione xml_parser_free() è una funzione built-in di PHP che libera la memoria associata a un parser XML. Appartiene all'estensione XML (Expat / SAX) di PHP e viene chiamata per rilasciare un parser una volta terminata la lettura di un documento.

Un parser SAX creato con xml_parser_create() legge un documento come un flusso di eventi — un tag di apertura, dati di carattere, un tag di chiusura — e attiva i gestori di callback per ognuno. Poiché il parser mantiene buffer interni e riferimenti a questi gestori, chiamare xml_parser_free() al termine del parsing interrompe quei riferimenti in modo che la memoria possa essere recuperata.

Questa pagina spiega cosa fa la funzione, quando è effettivamente necessaria, e mostra un esempio di parsing completo ed eseguibile.

Sintassi

xml_parser_free(XMLParser $parser): bool

Valore restituito — restituisce true in caso di successo, oppure false se $parser non fa riferimento a un parser valido.

Nota sulla versione: In PHP 8.0 e versioni successive, xml_parser_create() restituisce un oggetto XMLParser anziché una risorsa. Chiamare xml_parser_free() non è più strettamente necessario — il parser viene liberato automaticamente quando l'oggetto esce dallo scope e viene raccolto dal garbage collector. La funzione è mantenuta per compatibilità con le versioni precedenti ed è ancora una buona pratica negli script a lunga esecuzione in cui si vuole che la memoria venga rilasciata immediatamente.

Quando dovresti chiamarla?

• Processi a lunga esecuzione (worker in coda, daemon, job batch da CLI) che creano molti parser — liberare ognuno mantiene la memoria costante invece di lasciarla crescere fino alla fine dello script.
• File XML grandi o numerosi, dove mantenere i buffer del parser più a lungo del necessario spreca RAM.
• Prima di PHP 8.0, dove il parser era una risorsa e non era legato alla pulizia basata sullo scope, quindi liberarlo esplicitamente era l'unico modo affidabile per recuperare memoria nel mezzo di uno script.

Per uno script breve e occasionale che termina immediatamente dopo il parsing, la differenza è trascurabile — PHP rilascia tutto allo shutdown in ogni caso.

Esempio completo

Il frammento di codice seguente crea un parser, registra i gestori, analizza una stringa XML e poi libera il parser. I gestori raccolgono ogni titolo <book> in un array.

<?php
$xml = <<<XML
<?xml version="1.0"?>
<library>
  <book>PHP Basics</book>
  <book>Mastering XML</book>
</library>
XML;

$titles  = [];
$current = false;

// Fired on every opening tag
function startTag($parser, $name, $attrs) {
    global $current;
    $current = ($name === "BOOK"); // tag names are upper-cased by default
}

// Fired on every closing tag
function endTag($parser, $name) {
    global $current;
    $current = false;
}

// Fired for the text between tags
function charData($parser, $data) {
    global $current, $titles;
    if ($current && trim($data) !== "") {
        $titles[] = trim($data);
    }
}

$parser = xml_parser_create();
xml_set_element_handler($parser, "startTag", "endTag");
xml_set_character_data_handler($parser, "charData");

// Parse the whole document in one call (final argument = true)
xml_parse($parser, $xml, true);

// Release the parser's memory now that we are done
xml_parser_free($parser);

print_r($titles);

Output:

Array
(
    [0] => PHP Basics
    [1] => Mastering XML
)

Alcune cose da notare:

• I nomi degli elementi arrivano in maiuscolo per impostazione predefinita (BOOK, non book). Disabilita questa opzione con xml_parser_set_option() e il flag XML_OPTION_CASE_FOLDING se hai bisogno della distinzione maiuscole/minuscole originale.
• Il ciclo di vita è sempre lo stesso: crea → imposta i gestori → analizza → libera. I gestori xml_set_* (elemento e dati di carattere) svolgono il lavoro vero; xml_parser_free() chiude semplicemente il ciclo.
• Dopo aver chiamato xml_parser_free(), l'handle $parser non è più utilizzabile — crea un nuovo parser se hai bisogno di analizzare un altro documento.

Conclusione

xml_parser_free() rilascia la memoria occupata da un parser Expat/SAX creato con xml_parser_create(). Abbinala a xml_parser_create(), i tuoi gestori xml_set_* e xml_parse() per gestire la memoria in modo pulito. Da PHP 8.0 in poi il parser viene liberato automaticamente quando esce dallo scope, ma chiamare la funzione esplicitamente rimane un'abitudine sensata negli script a lunga esecuzione.

Esercizio