xml_set_object()

La funzione xml_set_object() è una funzione built-in di PHP che imposta l'oggetto a cui devono essere applicate le funzioni handler di un parser XML. Fa parte dell'estensione legacy XML Parser. Quando viene chiamata, il parser smette di trattare i nomi passati a funzioni come xml_set_element_handler() come funzioni globali e li tratta invece come metodi dell'oggetto fornito.

Questa pagina spiega cosa fa la funzione, la sua firma e i suoi parametri, un esempio completo eseguibile, gli errori comuni e come si relaziona al resto dell'API XML Parser.

Nota: xml_set_object() appartiene all'estensione legacy XML Parser (Expat) ed è deprecata a partire da PHP 8.4 — in alternativa, passa un callable di metodo appropriato (ad es. [$object, 'method']) direttamente alle funzioni xml_set_*_handler(). Per il nuovo codice, preferisci SimpleXML o DOMDocument, che modellano il documento come oggetti direttamente anziché utilizzare handler di callback.

Perché usarla

Senza xml_set_object(), ogni handler registrato deve essere una funzione autonoma (o una coppia stringa-metodo statico). Ciò rende difficile condividere lo stato tra gli handler — si finisce per ricorrere ai globali.

Associando il parser a un oggetto, puoi:

• Mantenere lo stato di parsing (uno stack, un contatore, il documento in costruzione) nelle proprietà dell'oggetto.
• Registrare nomi di metodi semplici come handler e farli risolvere rispetto a quell'oggetto.
• Incapsulare un intero parser come classe riutilizzabile.

Questo è il modo idiomatico per racchiudere l'API procedurale Expat in codice orientato agli oggetti.

Sintassi

xml_set_object(XMLParser $parser, object $object): bool

Parametri

Valore restituito

Restituisce true in caso di successo e false in caso di fallimento. (A partire da PHP 8.0 $parser è un'istanza XMLParser; in PHP 7 e versioni precedenti era una risorsa.)

L'ordine è importante: chiama xml_set_object() prima di registrare gli handler come xml_set_element_handler() o xml_set_character_data_handler(). I nomi degli handler registrati dopo che l'oggetto è stato impostato vengono cercati su quell'oggetto.

Esempio: associare un parser a un oggetto

Supponiamo di avere una stringa XML da analizzare con l'estensione XML Parser. Crea un parser con xml_parser_create(), associalo a un oggetto handler con xml_set_object(), quindi registra gli handler degli elementi per nome di metodo:

class MyHandler {
    function startElement($parser, $name, $attribs) {
        echo "Start element: $name\n";
    }
    function endElement($parser, $name) {
        echo "End element: $name\n";
    }
}

$handler    = new MyHandler();
$xmlParser  = xml_parser_create();
xml_set_object($xmlParser, $handler);
xml_set_element_handler($xmlParser, "startElement", "endElement");

$xmlData = '<root><item>Test</item></root>';
xml_parse($xmlParser, $xmlData, true);
xml_parser_free($xmlParser);

Output:

Start element: ROOT
Start element: ITEM
End element: ITEM
End element: ROOT

I nomi degli elementi arrivano in maiuscolo per impostazione predefinita, poiché il case folding è attivo a meno che non lo si disabiliti con xml_parser_set_option(). Il primo parametro di ogni handler è il parser stesso, non l'oggetto associato — all'interno del metodo hai già $this, quindi quel primo argomento è raramente usato.

Esempio: accumulare stato nell'oggetto

Il vero vantaggio è lo stato condiviso. Qui l'oggetto mantiene una profondità progressiva in modo da poter stampare l'albero in modo leggibile — qualcosa che richiederebbe un globale senza xml_set_object():

class TreePrinter {
    private int $depth = 0;

    function open($parser, $name) {
        echo str_repeat("  ", $this->depth) . "<$name>\n";
        $this->depth++;
    }
    function close($parser, $name) {
        $this->depth--;
        echo str_repeat("  ", $this->depth) . "</$name>\n";
    }
}

$parser = xml_parser_create();
xml_set_object($parser, new TreePrinter());
xml_set_element_handler($parser, "open", "close");
xml_parse($parser, "<a><b><c/></b></a>", true);
xml_parser_free($parser);

Output:

<A>
  <B>
    <C>
    </C>
  </B>
</A>

Errori comuni

• Imposta prima l'oggetto. Registrare un handler prima di xml_set_object() risolve il nome come funzione globale, non come metodo.
• I nomi degli handler sono stringhe. Passa il nome del metodo ("open"), non un array callable. È l'associazione che indica al parser di cercare il nome sull'oggetto.
• Libera il parser. Chiama xml_parser_free() al termine (le versioni moderne di PHP eseguono anche la pulizia automaticamente).
• È legacy. I nuovi progetti dovrebbero usare SimpleXML o DOMDocument invece.

Funzioni correlate

• xml_parser_create() — crea il parser a cui ci si associa.
• xml_set_element_handler() — registra gli handler per i tag di apertura/chiusura.
• xml_set_character_data_handler() — gestisce il testo tra i tag.
• xml_parse() — invia XML al parser.
• xml_parser_free() — rilascia il parser.

Conclusione

xml_set_object() associa un parser XML a un oggetto in modo che i nomi degli handler registrati in seguito si risolvano come metodi di quell'oggetto. Il vantaggio è l'incapsulamento: lo stato di parsing vive nelle proprietà dell'oggetto anziché nei globali, e un intero parser può essere organizzato come classe. Ricorda di chiamarla prima di registrare gli handler, e che la funzione fa parte dell'estensione Expat legacy — per il nuovo codice, preferisci SimpleXML o DOMDocument.

Esercizio