xml_set_object()

La fonction xml_set_object() est une fonction intégrée PHP qui définit l'objet auquel les fonctions de gestionnaire d'un analyseur XML doivent être appliquées. Elle fait partie de l'extension héritée XML Parser. Lorsque vous l'appelez, l'analyseur cesse de traiter les noms que vous passez aux fonctions comme xml_set_element_handler() en tant que fonctions globales et les traite à la place comme des méthodes de l'objet fourni.

Cette page explique ce que fait la fonction, sa signature et ses paramètres, un exemple complet exécutable, les pièges courants, et comment elle s'articule avec le reste de l'API XML Parser.

Remarque : xml_set_object() appartient à l'extension héritée XML Parser (Expat) et est dépréciée depuis PHP 8.4 — utilisez plutôt un callable de méthode approprié (par ex. [$object, 'method']) directement dans les fonctions xml_set_*_handler(). Pour le nouveau code, préférez SimpleXML ou DOMDocument, qui modélisent le document en tant qu'objets directement au lieu d'utiliser des gestionnaires de rappel.

Pourquoi l'utiliser

Sans xml_set_object(), chaque gestionnaire enregistré doit être une fonction autonome (ou une paire chaîne/méthode statique). Cela rend difficile le partage d'état entre les gestionnaires — on finit par recourir aux variables globales.

En liant l'analyseur à un objet, vous pouvez :

• Conserver l'état d'analyse (une pile, un compteur, le document en cours de construction) dans les propriétés de l'objet.
• Enregistrer des noms de méthodes simples comme gestionnaires et les résoudre sur cet objet.
• Encapsuler un analyseur entier dans une classe réutilisable.

C'est la manière idiomatique d'encapsuler l'API procédurale Expat dans du code orienté objet.

Syntaxe

xml_set_object(XMLParser $parser, object $object): bool

Paramètres

Valeur de retour

Retourne true en cas de succès et false en cas d'échec. (Depuis PHP 8.0, $parser est une instance XMLParser ; en PHP 7 et antérieur, c'était une ressource.)

L'ordre est important : appelez xml_set_object() avant d'enregistrer des gestionnaires tels que xml_set_element_handler() ou xml_set_character_data_handler(). Les noms de gestionnaires enregistrés après la définition de l'objet sont recherchés sur cet objet.

Exemple : lier un analyseur à un objet

Supposons que vous ayez une chaîne XML à analyser avec l'extension XML Parser. Créez un analyseur avec xml_parser_create(), liez-le à un objet gestionnaire avec xml_set_object(), puis enregistrez les gestionnaires d'éléments par nom de méthode :

class MyHandler {
    function startElement($parser, $name, $attribs) {
        echo "Start element: $name\n";
    }
    function endElement($parser, $name) {
        echo "End element: $name\n";
    }
}

$handler    = new MyHandler();
$xmlParser  = xml_parser_create();
xml_set_object($xmlParser, $handler);
xml_set_element_handler($xmlParser, "startElement", "endElement");

$xmlData = '<root><item>Test</item></root>';
xml_parse($xmlParser, $xmlData, true);
xml_parser_free($xmlParser);

Sortie :

Start element: ROOT
Start element: ITEM
End element: ITEM
End element: ROOT

Les noms d'éléments arrivent en majuscules par défaut, car le repliement de casse est activé sauf si vous le désactivez avec xml_parser_set_option(). Le premier paramètre de chaque gestionnaire est l'analyseur lui-même, pas l'objet lié — à l'intérieur de la méthode vous avez déjà $this, donc ce premier argument est rarement utilisé.

Exemple : accumuler un état dans l'objet

Le véritable avantage est l'état partagé. Ici l'objet maintient une profondeur courante pour pouvoir afficher l'arbre avec indentation — quelque chose qui nécessiterait une variable globale sans xml_set_object() :

class TreePrinter {
    private int $depth = 0;

    function open($parser, $name) {
        echo str_repeat("  ", $this->depth) . "<$name>\n";
        $this->depth++;
    }
    function close($parser, $name) {
        $this->depth--;
        echo str_repeat("  ", $this->depth) . "</$name>\n";
    }
}

$parser = xml_parser_create();
xml_set_object($parser, new TreePrinter());
xml_set_element_handler($parser, "open", "close");
xml_parse($parser, "<a><b><c/></b></a>", true);
xml_parser_free($parser);

Sortie :

<A>
  <B>
    <C>
    </C>
  </B>
</A>

Pièges courants

• Définissez d'abord l'objet. Enregistrer un gestionnaire avant xml_set_object() résout le nom comme une fonction globale, pas comme une méthode.
• Les noms de gestionnaires sont des chaînes. Passez le nom de la méthode ("open"), pas un tableau callable. C'est la liaison qui indique à l'analyseur de rechercher le nom sur l'objet.
• Libérez l'analyseur. Appelez xml_parser_free() lorsque vous avez terminé (les versions modernes de PHP nettoient aussi automatiquement).
• C'est du code hérité. Les nouveaux projets devraient utiliser SimpleXML ou DOMDocument à la place.

Fonctions associées

• xml_parser_create() — créer l'analyseur auquel vous vous liez.
• xml_set_element_handler() — enregistrer des gestionnaires pour les balises ouvrantes/fermantes.
• xml_set_character_data_handler() — gérer le texte entre les balises.
• xml_parse() — alimenter l'analyseur en XML.
• xml_parser_free() — libérer l'analyseur.

Conclusion

xml_set_object() lie un analyseur XML à un objet afin que les noms de gestionnaires enregistrés ensuite soient résolus comme méthodes de cet objet. L'avantage est l'encapsulation : l'état d'analyse réside dans les propriétés de l'objet plutôt que dans des variables globales, et un analyseur entier peut être empaqueté dans une classe. N'oubliez pas de l'appeler avant d'enregistrer les gestionnaires, et que la fonction fait partie de l'extension Expat héritée — pour le nouveau code, utilisez SimpleXML ou DOMDocument.

Pratique