addChild()

Introduzione

SimpleXMLElement::addChild() è il metodo che si usa per costruire XML da zero in PHP, nodo per nodo. SimpleXML è un'estensione PHP integrata che trasforma un documento XML in un object manipolabile con la normale sintassi delle proprietà. Mentre la lettura è semplice come $xml->book->title, creare un elemento nuovo è il compito di addChild().

Questa pagina spiega cosa restituisce addChild() e perché questo è importante, come aggiungere valori e namespace, e le insidie più comuni (escaping delle entità, attributi vs. elementi e il problema del valore NULL). Ogni esempio qui sotto è eseguibile.

Sintassi

public SimpleXMLElement::addChild(
    string $qualifiedName,
    ?string $value = null,
    ?string $namespace = null
): ?SimpleXMLElement

• $qualifiedName — il nome (tag) del nuovo elemento figlio, ad es. "title".
• $value — contenuto testuale opzionale per l'elemento. Se omesso o null, viene creato un elemento vuoto (<title/>).
• $namespace — URI del namespace opzionale a cui appartiene il figlio.

Il valore restituito è il dettaglio chiave: addChild() restituisce il nuovo elemento figlio appena creato, non il genitore. Quell'object restituito è quello su cui si concatenano ulteriori chiamate per costruire strutture annidate.

Aggiungere un singolo figlio

Questo stampa:

<?xml version="1.0"?>
<books><book>PHP Basics</book></books>

Si parte da un elemento radice <books>, poi si aggiunge un figlio <book> il cui contenuto testuale è PHP Basics. asXML() serializza l'object in una string XML.

Costruire una struttura annidata

Poiché addChild() restituisce il figlio appena creato, bisogna catturare quel valore di ritorno per continuare ad aggiungere livelli più profondi:

<?php

$xml  = new SimpleXMLElement('<books></books>');
$book = $xml->addChild('book');          // returns the <book> element
$book->addChild('title', 'PHP Basics');  // adds <title> inside <book>
$book->addChild('author', 'John Doe');   // adds <author> inside <book>

echo $xml->asXML();

Output:

<?xml version="1.0"?>
<books><book><title>PHP Basics</title><author>John Doe</author></book></books>

Se si fosse chiamato $xml->addChild('title', ...) invece di $book->addChild(...), il <title> sarebbe finito accanto a <book> anziché al suo interno. L'object su cui si chiama addChild() è sempre il genitore.

Figli vs. attributi

addChild() crea solo elementi. Per aggiungere un attributo (ad es. id="1"), si usa addAttribute() sullo stesso elemento:

<?php

$xml  = new SimpleXMLElement('<books></books>');
$book = $xml->addChild('book');
$book->addAttribute('id', '1');
$book->addChild('title', 'PHP Basics');

echo $xml->asXML();

Output:

<?xml version="1.0"?>
<books><book id="1"><title>PHP Basics</title></book></books>

Caratteri speciali: un'insidia concreta

Ci si potrebbe aspettare che addChild() effettui l'escape dei caratteri non sicuri per XML nel valore in automatico. Non lo fa completamente — passare una & grezza fa sì che SimpleXML la interpreti come inizio di un riferimento a entità ed emetta un avviso "unterminated entity reference", perdendo il contenuto:

<?php

$xml = new SimpleXMLElement('<docs></docs>');
$xml->addChild('note', 'Tom & Jerry <fun>'); // Warning: unterminated entity reference

echo $xml->asXML();

Questo stampa un elemento vuoto, non il testo desiderato:

<?xml version="1.0"?>
<docs><note/></docs>

Il modo affidabile per impostare testo contenente &, < o > è l'assegnazione tramite proprietà, che effettua l'escape correttamente:

<?php

$xml = new SimpleXMLElement('<docs></docs>');
$xml->note = 'Tom & Jerry <fun>';

echo $xml->asXML();

Output:

<?xml version="1.0"?>
<docs><note>Tom &amp; Jerry &lt;fun&gt;</note></docs>

Quindi: usare addChild() per creare l'elemento, ma assegnare il testo con caratteri speciali o non attendibili tramite la proprietà (oppure pre-effettuare l'escape con htmlspecialchars() prima di passarlo).

Aggiungere figli con namespace

Il terzo argomento associa il figlio a un URI di namespace:

<?php

$xml = new SimpleXMLElement('<feed xmlns:dc="http://purl.org/dc/elements/1.1/"></feed>');
$xml->addChild('creator', 'Jane Roe', 'http://purl.org/dc/elements/1.1/');

echo $xml->asXML();

Output:

<?xml version="1.0"?>
<feed xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:creator>Jane Roe</dc:creator></feed>

Insidie comuni

• Non ignorare il valore restituito quando si annida. addChild() restituisce il nuovo figlio; bisogna concatenare su quello, non sulla radice, altrimenti gli elementi risultano piatti.
• null vs. string vuota. addChild('tag') e addChild('tag', null) creano entrambi un elemento vuoto auto-chiudente (<tag/>). Passare '' per un nodo di testo vuoto ma presente.
• I valori non vengono sottoposti a escape in modo sicuro. Una & grezza nel valore provoca un avviso di riferimento a entità e la perdita del testo; assegnare il contenuto con caratteri speciali tramite proprietà ($el->tag = $text;) o pre-effettuare l'escape. I nomi degli elementi devono essere identificatori XML validi.
• Modifica in place. addChild() modifica il documento che l'object racchiude; non esiste un passaggio di "salvataggio" separato al di là della serializzazione con asXML().

Quando usarlo

Usare addChild() ogni volta che si ha bisogno di generare XML — costruendo un feed RSS/Atom, una sitemap, un file di configurazione o un payload API — e si apprezza già la sintassi object leggera di SimpleXML. Per analizzare XML esistente si parte tipicamente da simplexml_load_string() o simplexml_load_file(), poi si legge con children(). Per documenti che richiedono modifiche pesanti (spostamento/rimozione di nodi), l'estensione DOM è più adatta.

Conclusione

SimpleXMLElement::addChild() aggiunge un elemento figlio a un nodo XML e restituisce quel nuovo figlio in modo da poter costruire alberi annidati in modo fluente. Ricordare l'essenziale: restituisce il figlio, i caratteri speciali grezzi nel valore richiedono l'assegnazione tramite proprietà o il pre-escaping, gli attributi richiedono addAttribute(), e il terzo argomento opzionale inserisce il figlio in un namespace. Vedere PHP SimpleXML per una visione più ampia del lavoro con XML in PHP.

Pratica