simplexml_import_dom()

Introduzione

PHP offre due modi distinti per gestire XML: l'estensione DOM, potente e conforme agli standard ma verbosa, e SimpleXML, che cede parte di quella potenza in cambio di un'API molto più amichevole basata sulle proprietà degli oggetti. simplexml_import_dom() è il ponte tra le due — prende un nodo di un albero DOM e restituisce un SimpleXMLElement che racchiude gli stessi dati.

Questo è utile quando hai svolto un lavoro intenso con DOM (validazione rispetto a uno schema, utilizzo di XPath, manipolazione degli spazi dei nomi) ma vuoi leggere il risultato con la sintassi concisa di SimpleXML. Questa pagina spiega come funziona la funzione, quando usarla e le insidie più comuni.

Sintassi

simplexml_import_dom(
    object $node,
    ?string $class_name = SimpleXMLElement::class
): SimpleXMLElement|null

• $node — il nodo DOM da importare. In pratica si tratta di un'istanza di DOMNode, DOMElement o DOMDocument. Se si passa un DOMDocument, viene importato il suo elemento documento (la radice).
• $class_name — una classe opzionale che estende SimpleXMLElement. L'oggetto restituito è un'istanza di questa classe, il che consente di aggiungere metodi helper personalizzati.

Restituisce un SimpleXMLElement in caso di successo, oppure null se il nodo non può essere importato. La funzione è disponibile a partire da PHP 5.1.3.

Importare un intero documento

Il caso più comune è analizzare o costruire un documento con DOM e poi passare la radice a SimpleXML per una lettura agevole:

<?php
$dom = new DOMDocument();
$dom->loadXML('<?xml version="1.0"?>
<book>
  <title>PHP Basics</title>
  <author>Jane Doe</author>
</book>');

$book = simplexml_import_dom($dom);

// Read with SimpleXML's property syntax instead of DOM method calls:
echo $book->title;   // PHP Basics
echo "\n";
echo $book->author;  // Jane Doe
?>

Passando l'oggetto $dom (un DOMDocument) si importa il suo elemento radice, quindi $book corrisponde a <book>. Confrontalo con l'equivalente DOM — $dom->getElementsByTagName('title')->item(0)->nodeValue — e il vantaggio di SimpleXML diventa evidente.

Importare un singolo elemento costruito programmaticamente

Puoi anche costruire un nodo con DOM e importare solo quel nodo:

Qui creiamo un elemento <title>, lo alleghiamo al documento e passiamo l'elemento radice del documento ($dom->documentElement) a simplexml_import_dom(). asXML() serializza poi il SimpleXMLElement nuovamente in una stringa.

Relazione con il resto dell'API SimpleXML

simplexml_import_dom() è l'inverso di dom_import_simplexml(), che converte un SimpleXMLElement di nuovo in un DOMElement. Insieme permettono di spostarsi liberamente tra le due estensioni:

Se parti da una stringa o da un file anziché da un albero DOM, di solito non hai bisogno di DOM — usa direttamente simplexml_load_string() o simplexml_load_file().

Insidie

• Dati condivisi sottostanti. Il SimpleXMLElement restituito è una vista sugli stessi dati a cui fa riferimento il nodo DOM, non una copia indipendente. Mantieni l'oggetto DOM originale nello scope — se viene sottoposto a garbage collection, il wrapper SimpleXML può diventare inutilizzabile.
• Input non valido restituisce null. Un ritorno null (o, in PHP 8+, un TypeError se l'argomento non è affatto un oggetto DOM) segnala un errore — controlla sempre prima di concatenare chiamate di metodo.
• La classe personalizzata deve estendere SimpleXMLElement. Passare un nome di classe non correlato per $class_name è un errore; la classe deve essere una sottoclasse.

Conclusione

simplexml_import_dom() ti permette di svolgere un lavoro preciso con l'estensione DOM e poi leggere o serializzare il risultato con la sintassi leggera di SimpleXML. Si abbina naturalmente a dom_import_simplexml() per il percorso di ritorno verso DOM. Quando i tuoi dati risiedono già in un albero DOM, questa funzione è il modo più pulito per continuare con l'accesso tramite proprietà degli oggetti anziché con le verbose chiamate DOM.

Pratica