getDocNamespaces()

Introduction

SimpleXML est une extension PHP qui fournit une API simple et orientée objet pour lire des documents XML. Les espaces de noms XML permettent à deux vocabulaires de partager un même document sans que leurs noms d'éléments entrent en collision — chaque espace de noms est identifié par un URI et généralement référencé par un court préfixe (par exemple, bk dans <bk:title>).

SimpleXMLElement::getDocNamespaces() est la méthode qui vous indique quels espaces de noms un document déclare. Vous y faites généralement appel avant d'appeler children() ou xpath() sur des données avec espaces de noms, car vous avez besoin des URI pour adresser ces nœuds. Ce chapitre couvre la syntaxe, la différence que fait le drapeau $recursive, le piège de l'espace de noms par défaut, et en quoi cette méthode diffère de getNamespaces(), qui lui ressemble.

Syntaxe

public SimpleXMLElement::getDocNamespaces(bool $recursive = false, bool $from_root = true): array

• $recursive — quand il vaut false (valeur par défaut), seuls les espaces de noms déclarés sur l'élément racine sont retournés. Quand il vaut true, toute l'arborescence du document est parcourue et les espaces de noms déclarés sur n'importe quel descendant sont également inclus.
• $from_root — quand il vaut true (valeur par défaut), le parcours commence depuis la racine du document, même si vous appelez la méthode sur un sous-élément. Mettez-le à false pour parcourir uniquement à partir du nœud courant vers le bas.

La valeur de retour est un array associatif qui associe chaque préfixe d'espace de noms (la string avant les deux-points) à son URI.

Exemple de base

Ce document déclare un espace de noms, bk, sur son élément racine :

Résultat :

Prefix: bk, URI: https://example.com/books

La méthode retourne un array associatif, donc un foreach avec $prefix => $uri parcourt chaque déclaration en une seule boucle.

Ce que $recursive change réellement

Ce drapeau n'a d'importance que lorsqu'un espace de noms est déclaré en dessous de la racine. Ici, lib est sur la racine mais dc est déclaré sur un élément <details> imbriqué :

<?php

$xml = new SimpleXMLElement(
    '<library xmlns:lib="https://example.com/library">'
  . '  <lib:book>'
  . '    <details xmlns:dc="https://purl.org/dc/elements/1.1/">'
  . '      <dc:title>PHP Basics</dc:title>'
  . '    </details>'
  . '  </lib:book>'
  . '</library>'
);

echo "Root only:\n";
print_r($xml->getDocNamespaces(false));

echo "Whole document:\n";
print_r($xml->getDocNamespaces(true));

Résultat :

Root only:
Array
(
    [lib] => https://example.com/library
)
Whole document:
Array
(
    [lib] => https://example.com/library
    [dc] => https://purl.org/dc/elements/1.1/
)

Passez true chaque fois que vous ne pouvez pas garantir que chaque espace de noms est déclaré sur la racine — les flux et les documents agrégés déclarent souvent des espaces de noms supplémentaires plus profondément dans l'arborescence.

Le piège de l'espace de noms par défaut

Un espace de noms déclaré avec xmlns="..." (sans préfixe) est l'espace de noms par défaut du document. getDocNamespaces() le retourne sous une clé de string vide, et non sous l'URI :

<?php

$xml = new SimpleXMLElement(
    '<feed xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/">'
  . '<entry><title>Hello</title></entry>'
  . '</feed>'
);

print_r($xml->getDocNamespaces(true));

Résultat :

Array
(
    [] => http://www.w3.org/2005/Atom
    [media] => http://search.yahoo.com/mrss/
)

Vous aurez besoin de cet URI à clé vide pour lire les nœuds dont l'espace de noms est le défaut, par exemple $xml->children('http://www.w3.org/2005/Atom'), ou en l'enregistrant avec registerXPathNamespace() avant une requête xpath().

getDocNamespaces() vs getNamespaces()

Ces deux méthodes sont faciles à confondre :

En résumé : getDocNamespaces() répond à la question « que définit ce document ? » tandis que getNamespaces() répond à « que cette partie du document utilise-t-elle ? ».

Quand l'utiliser

• Avant d'interroger des nœuds avec espaces de noms — transmettez les URI retournés à children($uri) ou à registerXPathNamespace().
• Lors de la consommation de XML tiers (RSS/Atom, SOAP, RSS Media, SVG) dont vous ne contrôlez pas les préfixes.
• Pour inspecter ou valider les déclarations d'espaces de noms d'un document inconnu.

Conclusion

SimpleXMLElement::getDocNamespaces() retourne un array associatif des préfixes d'espaces de noms et des URI déclarés dans un document XML. Utilisez la valeur par défaut (false) lorsque tous les espaces de noms se trouvent sur la racine, et passez true pour parcourir toute l'arborescence. N'oubliez pas que l'espace de noms par défaut (sans préfixe) est retourné sous une clé de string vide, et utilisez plutôt getNamespaces() lorsque vous vous intéressez aux espaces de noms réellement utilisés plutôt que simplement déclarés.

Entraînement