simplexml_import_dom()

Introdução

O PHP oferece duas formas distintas de lidar com XML: a extensão DOM, poderosa e compatível com padrões, mas verbosa, e o SimpleXML, que troca parte desse poder por uma API muito mais amigável, baseada em propriedades de objetos. simplexml_import_dom() é a ponte entre os dois — ela recebe um nó de uma árvore DOM e retorna um SimpleXMLElement que encapsula os mesmos dados.

Isso é útil quando você realizou operações complexas com DOM (validação contra um esquema, uso de XPath, manipulação de namespaces) mas quer ler o resultado com a sintaxe concisa do SimpleXML. Esta página explica como a função funciona, quando utilizá-la e os problemas comuns que podem surgir.

Sintaxe

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

• $node — o nó DOM a ser importado. Na prática, trata-se de uma instância de DOMNode, DOMElement ou DOMDocument. Se você passar um DOMDocument, o elemento do documento (a raiz) é importado.
• $class_name — uma classe opcional que estende SimpleXMLElement. O objeto retornado é uma instância dessa classe, o que permite adicionar seus próprios métodos auxiliares.

Retorna um SimpleXMLElement em caso de sucesso, ou null se o nó não puder ser importado. A função está disponível desde o PHP 5.1.3.

Importando um documento inteiro

O caso mais comum é analisar ou construir um documento com DOM e depois passar a raiz para o SimpleXML para leitura fácil:

<?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
?>

Passar o objeto $dom (um DOMDocument) importa seu elemento raiz, portanto $book corresponde a <book>. Compare isso com o equivalente em DOM — $dom->getElementsByTagName('title')->item(0)->nodeValue — e o apelo do SimpleXML fica evidente.

Importando um único elemento criado

Você também pode criar um nó programaticamente com DOM e importar apenas esse nó:

Aqui criamos um elemento <title>, o anexamos ao documento e passamos o elemento raiz do documento ($dom->documentElement) para simplexml_import_dom(). asXML() então serializa o SimpleXMLElement de volta para uma string.

Relação com o restante da API SimpleXML

simplexml_import_dom() é o inverso de dom_import_simplexml(), que converte um SimpleXMLElement de volta em um DOMElement. Juntas, elas permitem transitar livremente entre as duas extensões:

Se você está partindo de uma string ou de um arquivo em vez de uma árvore DOM, geralmente não precisa do DOM — use simplexml_load_string() ou simplexml_load_file() diretamente.

Problemas comuns

• Dados subjacentes compartilhados. O SimpleXMLElement retornado é uma visão sobre os mesmos dados que o nó DOM referencia, não uma cópia independente. Mantenha o objeto DOM original no escopo — se ele for coletado pelo garbage collector, o wrapper SimpleXML pode se tornar inutilizável.
• Entrada inválida retorna null. Um retorno null (ou, no PHP 8+, um TypeError se o argumento não for um objeto DOM) indica falha — sempre verifique antes de encadear chamadas de método.
• A classe personalizada deve estender SimpleXMLElement. Passar um nome de classe não relacionado para $class_name é um erro; a classe precisa ser uma subclasse.

Conclusão

simplexml_import_dom() permite realizar trabalho preciso com a extensão DOM e depois ler ou serializar o resultado com a sintaxe leve do SimpleXML. Ela se combina naturalmente com dom_import_simplexml() para o caminho de volta ao DOM. Quando seus dados já estão em uma árvore DOM, essa função é a forma mais limpa de continuar com acesso por propriedades de objeto em vez de chamadas DOM verbosas.

Prática