addChild()

Introducción

SimpleXMLElement::addChild() es el método que se usa para construir XML desde cero en PHP, nodo por nodo. SimpleXML es una extensión integrada de PHP que convierte un documento XML en un objeto que puedes leer y escribir con la sintaxis de propiedades habitual. Si bien leer es tan sencillo como $xml->book->title, escribir un elemento completamente nuevo es tarea de addChild().

Esta página cubre qué devuelve addChild() y por qué importa, cómo añadir valores y espacios de nombres, y los errores comunes que confunden a la gente (escape de entidades, atributos vs. elementos y el problema del valor NULL). Cada ejemplo es ejecutable.

Sintaxis

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

• $qualifiedName — el nombre (etiqueta) del nuevo elemento hijo, p. ej. "title".
• $value — contenido de texto opcional para el elemento. Si se omite o es null, se crea un elemento vacío (<title/>).
• $namespace — URI de espacio de nombres opcional al que pertenece el hijo.

El valor de retorno es el detalle clave: addChild() devuelve el elemento hijo recién creado, no el padre. Ese objeto devuelto es en el que encadenas nuevas llamadas para construir estructuras anidadas.

Añadir un único hijo

Esto imprime:

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

Partimos de un elemento raíz <books>, luego añadimos un hijo <book> cuyo contenido de texto es PHP Basics. asXML() serializa el objeto de vuelta a una cadena XML.

Construir una estructura anidada

Dado que addChild() devuelve el hijo que acaba de crear, capturas ese valor de retorno para seguir añadiendo niveles más 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();

Salida:

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

Si hubieras llamado a $xml->addChild('title', ...) en lugar de $book->addChild(...), el <title> habría quedado junto a <book> en vez de dentro de él. El objeto sobre el que llamas addChild() es siempre el padre.

Hijos vs. atributos

addChild() solo crea elementos. Para añadir un atributo (p. ej. id="1"), usa addAttribute() sobre el mismo elemento:

<?php

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

echo $xml->asXML();

Salida:

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

Caracteres especiales: un error común real

Podrías esperar que addChild() escape por ti los caracteres no seguros para XML en el valor. No lo hace completamente — pasar un & sin procesar hace que SimpleXML lo trate como el inicio de una referencia de entidad y emita una advertencia "unterminated entity reference", descartando el contenido:

<?php

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

echo $xml->asXML();

Esto imprime un elemento vacío, no el texto que querías:

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

La forma fiable de establecer texto que contenga &, < o > es la asignación de propiedades, que escapa correctamente:

<?php

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

echo $xml->asXML();

Salida:

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

Por tanto: usa addChild() para crear el elemento, pero asigna texto que contenga caracteres especiales o no confiables a través de la propiedad (o escápalo previamente con htmlspecialchars() antes de pasarlo).

Añadir hijos con espacio de nombres

El tercer argumento asocia el hijo con una URI de espacio de nombres:

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

Salida:

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

Errores comunes

• No ignores el valor de retorno al anidar. addChild() devuelve el nuevo hijo; encadena sobre ese, no sobre la raíz, o tus elementos quedarán al mismo nivel.
• null vs. cadena vacía. addChild('tag') y addChild('tag', null) crean un elemento vacío de autocierre (<tag/>). Pasa '' para un nodo de texto vacío pero presente.
• Los valores no se escapan de forma segura. Un & sin procesar en el valor provoca una advertencia de referencia de entidad y pierde el texto; asigna contenido con caracteres especiales mediante la propiedad ($el->tag = $text;) o escápalo previamente. Los nombres de elementos deben ser identificadores XML válidos.
• Muta en su lugar. addChild() modifica el documento que envuelve el objeto; no hay un paso de "guardar" aparte más allá de serializar con asXML().

Cuándo usarlo

Recurre a addChild() siempre que necesites generar XML — construir un feed RSS/Atom, un sitemap, un archivo de configuración o un payload de API — y ya te guste la sintaxis de objeto ligera de SimpleXML. Para analizar XML existente normalmente empezarías con simplexml_load_string() o simplexml_load_file(), y luego leerías con children(). Para documentos que requieren edición intensiva (mover o eliminar nodos), la extensión DOM es una mejor opción.

Conclusión

SimpleXMLElement::addChild() añade un elemento hijo a un nodo XML y devuelve ese nuevo hijo para que puedas construir árboles anidados de forma fluida. Recuerda los puntos esenciales: devuelve el hijo, los caracteres especiales en el valor necesitan asignación de propiedad o escape previo, los atributos requieren addAttribute() y el tercer argumento opcional coloca al hijo en un espacio de nombres. Consulta PHP SimpleXML para una visión más amplia del trabajo con XML en PHP.

Práctica