addChild()

Introdução

SimpleXMLElement::addChild() é o método utilizado para construir XML do zero em PHP, nó por nó. SimpleXML é uma extensão PHP nativa que transforma um documento XML em um objeto que você pode ler e escrever com a sintaxe comum de propriedades. Enquanto a leitura é tão simples quanto $xml->book->title, escrever um novo elemento é tarefa do addChild().

Esta página cobre o que addChild() retorna e por que isso importa, como adicionar valores e namespaces, e as armadilhas que podem te pegar de surpresa (escape de entidades, atributos versus elementos e a armadilha do valor null). Cada exemplo abaixo é executável.

Sintaxe

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

• $qualifiedName — o nome (tag) do novo elemento filho, por exemplo "title".
• $value — conteúdo de texto opcional para o elemento. Se omitido ou null, um elemento vazio é criado (<title/>).
• $namespace — URI de namespace opcional ao qual o filho pertence.

O valor de retorno é o detalhe principal: addChild() retorna o elemento filho recém-criado, não o pai. Esse objeto retornado é no que você encadeia chamadas adicionais para construir estruturas aninhadas.

Adicionando um único filho

Isso imprime:

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

Começamos a partir de um elemento raiz <books>, depois adicionamos um filho <book> cujo conteúdo de texto é PHP Basics. asXML() serializa o objeto de volta em uma string XML.

Construindo uma estrutura aninhada

Como addChild() retorna o filho que acabou de criar, você captura esse valor de retorno para continuar adicionando níveis mais profundos:

<?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();

Saída:

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

Se você tivesse chamado $xml->addChild('title', ...) em vez de $book->addChild(...), o <title> teria ficado ao lado de <book> em vez de dentro dele. O objeto no qual você chama addChild() é sempre o pai.

Filhos versus atributos

addChild() cria apenas elementos. Para adicionar um atributo (por exemplo id="1"), use addAttribute() no mesmo elemento:

<?php

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

echo $xml->asXML();

Saída:

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

Caracteres especiais: uma armadilha real

Você pode esperar que addChild() faça o escape de caracteres inseguros para XML no valor automaticamente. Ele não faz isso completamente — passar um & bruto faz o SimpleXML tratá-lo como início de uma referência de entidade e emite um aviso de "referência de entidade não terminada", descartando o conteúdo:

<?php

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

echo $xml->asXML();

Isso imprime um elemento vazio, não o texto desejado:

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

A maneira confiável de definir texto contendo &, < ou > é a atribuição por propriedade, que faz o escape corretamente:

<?php

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

echo $xml->asXML();

Saída:

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

Portanto: use addChild() para criar o elemento, mas atribua texto não confiável ou com caracteres especiais por meio da propriedade (ou faça o pré-escape com htmlspecialchars() antes de passá-lo).

Adicionando filhos com namespace

O terceiro argumento associa o filho a um URI de 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();

Saída:

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

Armadilhas comuns

• Não ignore o valor de retorno ao aninhar. addChild() retorna o novo filho; encadeie nele, não na raiz, ou seus elementos ficarão todos no mesmo nível.
• null versus string vazia. addChild('tag') e addChild('tag', null) criam um elemento vazio de autofechamento (<tag/>). Passe '' para um nó de texto vazio mas presente.
• Os valores não são escapados com segurança. Um & bruto no valor aciona um aviso de referência de entidade e perde o texto; atribua conteúdo com caracteres especiais por meio da propriedade ($el->tag = $text;) ou faça o pré-escape. Os nomes de elementos devem ser identificadores XML válidos.
• Muda o estado in-place. addChild() altera o documento que o objeto envolve; não há etapa separada de "salvar" além de serializar com asXML().

Quando usar

Use addChild() sempre que precisar gerar XML — construindo um feed RSS/Atom, um sitemap, um arquivo de configuração ou um payload de API — e já gostar da sintaxe de objeto leve do SimpleXML. Para analisar XML existente, geralmente você começaria com simplexml_load_string() ou simplexml_load_file(), e depois leria com children(). Para documentos que precisam de edição intensa (mover/remover nós), a extensão DOM é mais adequada.

Conclusão

SimpleXMLElement::addChild() adiciona um elemento filho a um nó XML e retorna esse novo filho para que você possa construir árvores aninhadas de forma fluente. Lembre-se dos pontos essenciais: ele retorna o filho, caracteres especiais brutos no valor precisam de atribuição por propriedade ou pré-escape, atributos precisam de addAttribute(), e o terceiro argumento opcional coloca o filho em um namespace. Consulte PHP SimpleXML para ter uma visão geral do trabalho com XML em PHP.

Prática