xml_set_start_namespace_decl_handler()

La fonction xml_set_start_namespace_decl_handler() enregistre un rappel que l'analyseur XML appelle chaque fois qu'il rencontre le début d'une déclaration de namespace — c'est-à-dire un attribut xmlns ou xmlns:prefix qui fait entrer un namespace dans la portée. Elle fait partie de l'extension XML Parser (SAX) de bas niveau et orientée événements de PHP, et n'a aucun rapport avec SimpleXML ou DOM, qui analysent l'intégralité du document en arbre plutôt qu'en flux d'événements.

Vous utilisez ce gestionnaire lorsque vous analysez du XML volumineux ou en flux continu et avez besoin de savoir quels namespaces sont actifs — par exemple, pour associer des préfixes à des URI, valider la présence d'un namespace requis, ou distribuer des éléments vers différents processeurs selon leur namespace.

Condition essentielle : les gestionnaires de namespace ne se déclenchent que si l'analyseur est conscient des namespaces. Vous devez créer l'analyseur avec xml_parser_create_ns(), et non xml_parser_create(). Un analyseur ordinaire ignore silencieusement les attributs xmlns, de sorte que ce gestionnaire ne sera jamais appelé.

Syntaxe

xml_set_start_namespace_decl_handler($parser, $handler): bool

La fonction retourne true en cas de succès ou false en cas d'échec.

La signature du rappel

Votre gestionnaire reçoit trois arguments :

function handler($parser, $prefix, $uri): void

• $parser — l'analyseur qui a déclenché l'événement.
• $prefix — le préfixe de namespace, par exemple "ns" pour xmlns:ns="…". Pour un namespace par défaut (xmlns="…"), le préfixe est le boolean false, et non une string vide.
• $uri — l'URI de namespace à laquelle le préfixe est lié.

Exemple : lecture des déclarations de namespace

L'exemple ci-dessous analyse un document de style Atom avec deux namespaces et affiche chacun d'eux au moment où il entre dans la portée. Notez l'utilisation de xml_parser_create_ns() pour que les événements se déclenchent réellement :

function handleStartNamespace($parser, $prefix, $uri) {
    // A default namespace (xmlns="...") arrives as prefix === false.
    $name = ($prefix === false) ? "(default)" : $prefix;
    echo "Namespace in scope -> $name = $uri\n";
}

$parser = xml_parser_create_ns();
xml_set_start_namespace_decl_handler($parser, "handleStartNamespace");

$xml = '<?xml version="1.0"?>
<root xmlns:ns="http://example.com/ns"
      xmlns:meta="http://example.com/meta">
  <ns:item>Test</ns:item>
</root>';

// The third argument `true` marks this as the final chunk of data.
xml_parse($parser, $xml, true);
xml_parser_free($parser);

Sortie :

Namespace in scope -> ns = http://example.com/ns
Namespace in scope -> meta = http://example.com/meta

L'analyseur déclenche un événement par namespace déclaré, dans l'ordre d'apparition des attributs xmlns, avant de signaler l'élément qui les a déclarés.

Pièges courants

• Analyseur ordinaire, aucun événement. Si vous créez l'analyseur avec xml_parser_create() au lieu de xml_parser_create_ns(), le gestionnaire n'est jamais appelé et vous ne verrez aucune sortie — une source fréquente de confusion du type « ça ne fonctionne pas ».
• Le préfixe de namespace par défaut est false. Comparez toujours avec === ($prefix === false) ; un test if (!$prefix) intercepte également le préfixe légitime "0".
• Associez-le au gestionnaire de fin. La fonction complémentaire xml_set_end_namespace_decl_handler() marque l'endroit où un namespace sort de la portée, ce qui importe lorsque vous suivez l'imbrication.
• Libérez l'analyseur. Appelez xml_parser_free() lorsque vous avez terminé pour libérer la ressource.

Fonctions associées

• xml_parser_create_ns() — crée l'analyseur conscient des namespaces requis par ce gestionnaire.
• xml_set_end_namespace_decl_handler() — le gestionnaire de fin de portée correspondant.
• xml_set_element_handler() — gère les balises de début/fin d'élément.
• xml_parse() — envoie des données à l'analyseur et déclenche les rappels.

Conclusion

xml_set_start_namespace_decl_handler() vous permet de réagir aux namespaces au moment où ils entrent dans la portée lors de l'analyse en flux XML avec l'analyseur SAX. Le seul point qui pose problème est l'analyseur : les événements de namespace ne se déclenchent que lorsque l'analyseur est créé avec xml_parser_create_ns(). Souvenez-vous qu'un namespace par défaut arrive avec un préfixe égal à false, associez le gestionnaire à xml_set_end_namespace_decl_handler() lorsque vous avez besoin du suivi de portée, et libérez l'analyseur une fois terminé.

Pratique