addChild()

Introduction

SimpleXMLElement::addChild() est la méthode utilisée pour construire du XML à partir de zéro en PHP, nœud par nœud. SimpleXML est une extension PHP intégrée qui transforme un document XML en objet que vous pouvez lire et modifier avec une syntaxe de propriété ordinaire. Là où la lecture est aussi simple que $xml->book->title, écrire un tout nouvel élément est le rôle de addChild().

Cette page explique ce que retourne addChild() et pourquoi c'est important, comment ajouter des valeurs et des espaces de noms, ainsi que les pièges courants (échappement des entités, attributs vs. éléments, et le piège de la valeur null). Chaque exemple ci-dessous est exécutable.

Syntaxe

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

• $qualifiedName — le nom (balise) du nouvel élément enfant, par ex. "title".
• $value — contenu texte optionnel de l'élément. S'il est omis ou null, un élément vide est créé (<title/>).
• $namespace — URI d'espace de noms optionnel auquel appartient l'enfant.

La valeur de retour est le détail clé : addChild() retourne l'élément enfant nouvellement créé, et non le parent. Cet objet retourné est celui sur lequel vous enchaînez d'autres appels pour construire des structures imbriquées.

Ajouter un seul enfant

Cela affiche :

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

On part d'un élément racine <books>, puis on ajoute un enfant <book> dont le contenu textuel est PHP Basics. asXML() sérialise l'objet en une chaîne XML.

Construire une structure imbriquée

Parce que addChild() retourne l'enfant qu'il vient de créer, vous capturez cette valeur de retour pour continuer à ajouter des niveaux plus profonds :

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

Résultat :

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

Si vous aviez appelé $xml->addChild('title', ...) plutôt que $book->addChild(...), le <title> se serait retrouvé à côté de <book> plutôt qu'à l'intérieur. L'objet sur lequel vous appelez addChild() est toujours le parent.

Enfants vs. attributs

addChild() crée uniquement des éléments. Pour ajouter un attribut (par ex. id="1"), utilisez addAttribute() sur le même élément :

<?php

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

echo $xml->asXML();

Résultat :

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

Caractères spéciaux : un vrai piège

Vous pourriez supposer que addChild() échappe automatiquement les caractères non sûrs pour XML dans la valeur. Ce n'est pas tout à fait le cas — passer un & brut amène SimpleXML à le traiter comme le début d'une référence d'entité et à émettre un avertissement "unterminated entity reference", perdant ainsi le contenu :

<?php

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

echo $xml->asXML();

Cela affiche un élément vide, pas le texte souhaité :

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

La façon fiable de définir un texte contenant &, < ou > est l'affectation par propriété, qui échappe correctement :

<?php

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

echo $xml->asXML();

Résultat :

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

Donc : utilisez addChild() pour créer l'élément, mais affectez le texte non fiable ou contenant des caractères spéciaux via la propriété (ou pré-échappez avec htmlspecialchars() avant de le passer).

Ajouter des enfants avec espace de noms

Le troisième argument associe l'enfant à un URI d'espace de noms :

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

Résultat :

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

Pièges courants

• Ne pas ignorer la valeur de retour lors de l'imbrication. addChild() retourne le nouvel enfant ; enchaînez sur celui-ci, pas sur la racine, sinon vos éléments se retrouvent à plat.
• null vs. chaîne vide. addChild('tag') et addChild('tag', null) créent tous deux un élément auto-fermant vide (<tag/>). Passez '' pour un nœud texte vide mais présent.
• Les valeurs ne sont pas correctement échappées. Un & brut dans la valeur déclenche un avertissement de référence d'entité et perd le texte ; affectez le contenu avec des caractères spéciaux via la propriété ($el->tag = $text;) ou pré-échappez-le. Les noms d'éléments doivent être des identifiants XML valides.
• Il modifie en place. addChild() modifie le document enveloppé par l'objet ; il n'y a pas d'étape de "sauvegarde" séparée au-delà de la sérialisation avec asXML().

Quand l'utiliser

Faites appel à addChild() chaque fois que vous avez besoin de générer du XML — construire un flux RSS/Atom, un sitemap, un fichier de configuration ou une charge utile d'API — et que vous appréciez déjà la syntaxe objet légère de SimpleXML. Pour analyser du XML existant, vous commenceriez généralement par simplexml_load_string() ou simplexml_load_file(), puis vous liriez avec children(). Pour les documents nécessitant une édition intensive (déplacement/suppression de nœuds), l'extension DOM est plus adaptée.

Conclusion

SimpleXMLElement::addChild() ajoute un élément enfant à un nœud XML et retourne ce nouvel enfant afin que vous puissiez construire des arborescences imbriquées de manière fluide. Retenez l'essentiel : il retourne l'enfant, les caractères spéciaux bruts dans la valeur nécessitent une affectation par propriété ou un pré-échappement, les attributs nécessitent addAttribute(), et le troisième argument optionnel place l'enfant dans un espace de noms. Voir PHP SimpleXML pour une vue d'ensemble du travail avec XML en PHP.

Pratique