xml_get_error_code()

La fonction xml_get_error_code() est une fonction PHP intégrée qui récupère le code d'erreur d'un analyseur XML. Lorsque vous analysez du XML avec l'extension XML Parser (Expat) de PHP, les fonctions d'analyse retournent false dès qu'un problème survient — mais false seul ne vous dit pas ce qui s'est passé. xml_get_error_code() retourne un code numérique décrivant l'erreur la plus récente, que vous pouvez ensuite traduire en message lisible avec xml_error_string().

Cette page couvre la syntaxe de la fonction, ce qu'elle retourne, comment convertir le code en message, et le piège qui surprend la plupart des gens : le code retourné est un code d'erreur Expat, et non la constante XML_OPTION_* que vous pourriez attendre.

Syntaxe

xml_get_error_code(XMLParser $parser): int

$parser est l'analyseur créé par xml_parser_create() (ou xml_parser_create_ns()). En PHP 8.0+, il s'agit d'un objet XMLParser ; en PHP 7.x et antérieur, c'était une resource. Le code de ce chapitre fonctionne dans les deux cas.

Valeur de retour

La fonction retourne un code d'erreur de type integer :

• 0 (la constante XML_ERROR_NONE) signifie aucune erreur — l'analyse a réussi.
• Toute valeur non nulle identifie le type d'échec. Passez-la à xml_error_string() pour obtenir une description lisible, et à xml_get_current_line_number() pour trouver l'endroit où c'est arrivé.

Vérifiez toujours la valeur de retour de la fonction d'analyse en premier (xml_parse() / xml_parse_into_struct()) ; n'appelez xml_get_error_code() qu'après qu'elle ait retourné false.

Un exemple complet et exécutable

L'exemple ci-dessous analyse une chaîne XML délibérément incorrecte (la balise fermante ne correspond pas à la balise ouvrante), puis signale le code d'erreur, son message et le numéro de ligne. Comme le XML est intégré sous forme de chaîne, vous pouvez le copier et l'exécuter tel quel — aucun fichier n'est nécessaire.

<?php
$broken = "<note><to>Ann</from></note>";   // </from> should be </to>

$parser = xml_parser_create();
if (!xml_parse_into_struct($parser, $broken, $values)) {
    $code = xml_get_error_code($parser);
    echo "Error code:  $code\n";
    echo "Message:     " . xml_error_string($code) . "\n";
    echo "On line:     " . xml_get_current_line_number($parser) . "\n";
}
xml_parser_free($parser);

Résultat :

Error code:  76
Message:     Mismatched tag
On line:     1

xml_parse_into_struct() retourne false, donc nous appelons xml_get_error_code() et passons le résultat directement à xml_error_string() pour obtenir le message "Mismatched tag".

Le piège : le code est un code Expat

Il est tentant de comparer le résultat à des constantes comme XML_ERROR_TAG_MISMATCH dans un switch :

switch ($code) {
    case XML_ERROR_TAG_MISMATCH:  // value 7
        // ...
}

Mais cette branche ne correspond jamais. L'analyseur Expat retourne 76 pour une balise non correspondante, tandis que XML_ERROR_TAG_MISMATCH est la constante 7 — ce sont des schémas de numérotation différents, donc la comparaison échoue silencieusement. L'approche fiable est de toujours convertir le code en texte avec xml_error_string() plutôt que de comparer des nombres bruts :

<?php
$samples = [
    'good'      => "<note><to>Ann</to></note>",
    'mismatch'  => "<note><to>Ann</from></note>",
    'truncated' => "<note><to>Ann",
];

foreach ($samples as $label => $xml) {
    $parser = xml_parser_create();
    $ok = xml_parse_into_struct($parser, $xml, $values);
    $code = xml_get_error_code($parser);
    printf("%-9s -> code %d (%s)\n", $label, $code, xml_error_string($code) ?: 'OK');
    xml_parser_free($parser);
}

Résultat :

good      -> code 0 (No error)
mismatch  -> code 76 (Mismatched tag)
truncated -> code 5 (Invalid document end)

Un code de 0 (XML_ERROR_NONE) confirme que le document a été analysé correctement, ce qui est exactement ce que produit l'échantillon bien formé good.

Afficher l'erreur à un utilisateur

Dans une application réelle — par exemple, un gestionnaire de fichier XML téléchargé — vous enregistrez généralement le détail technique et affichez le message convivial :

$parser = xml_parser_create();
$xml    = file_get_contents($_FILES['xml_file']['tmp_name']);

if (!xml_parse_into_struct($parser, $xml, $values)) {
    $code = xml_get_error_code($parser);
    $line = xml_get_current_line_number($parser);

    // For the logs / developers:
    error_log("XML parse failed on line $line: " . xml_error_string($code));

    // For the user:
    $userMessage = "We couldn't read that file — please check it is valid XML.";
}
xml_parser_free($parser);

Quand l'utiliser (et quand ne pas l'utiliser)

xml_get_error_code() appartient à l'extension XML Parser basée sur Expat — la même famille que xml_parser_create() et xml_parse_into_struct(). Utilisez-la lorsque vous effectuez une analyse événementielle/en flux avec cette extension et que vous devez réagir à un échec.

Si vous analysez du XML avec SimpleXML ou DOM, cette fonction ne s'applique pas — ceux-ci utilisent l'API d'erreurs libxml. Dans ce cas, utilisez libxml_get_last_error() (après avoir appelé libxml_use_internal_errors(true)) pour inspecter ce qui s'est passé. Consultez l'aperçu SimpleXML pour ce workflow.

Conclusion

xml_get_error_code() récupère le code d'erreur Expat numérique pour le dernier échec sur une instance XML Parser. Le modèle fiable est : vérifiez la valeur de retour de la fonction d'analyse, et si elle est false, appelez xml_get_error_code() et passez le résultat à xml_error_string() pour un message lisible — ne comparez pas le code brut aux constantes XML_ERROR_*, car la numérotation Expat ne correspond pas à celles-ci. Associez-la à xml_get_current_line_number() pour indiquer aux utilisateurs (et à vos journaux) l'endroit exact où le document a échoué.

Pratique