xml_error_string()

La funzione xml_error_string() è una funzione built-in di PHP che recupera una descrizione testuale di un errore del parser XML. Appartiene alla vecchia estensione XML Parser. Quando si analizzano file XML usando SimpleXML o altre librerie moderne, gli errori vengono tipicamente gestiti con libxml_get_errors(), poiché l'estensione xml legacy è deprecata nelle versioni moderne di PHP.

La funzione xml_error_string() è utile quando è necessario recuperare un messaggio di errore leggibile per flussi di lavoro di parsing XML legacy, anche se le applicazioni moderne dovrebbero preferire libxml_get_errors() per SimpleXML.

Sintassi

La sintassi della funzione xml_error_string() è la seguente:

sintassi della funzione xml_error_string()

xml_error_string(int $error_code): string|false

Parametri

• $error_code — un codice di errore intero, come restituito da xml_get_error_code(). L'estensione XML Parser espone questi codici come costanti XML_ERROR_* (ad esempio, XML_ERROR_NONE è 0, che significa "nessun errore").

Valore restituito

xml_error_string() restituisce una string leggibile che descrive il codice di errore dato (come "Attribute without value"). Se il codice è sconosciuto, restituisce false. Si noti che la funzione si limita a tradurre un codice in testo — non indica dove nel documento si è verificato l'errore; per questo occorre anche xml_get_current_line_number() e xml_get_current_column_number().

Esempi d'uso

Vediamo alcuni esempi pratici dell'utilizzo di xml_error_string() in PHP.

Esempio 1: Recupero di una stringa di errore del parser XML (Parser XML legacy)

La funzione xml_error_string() funziona con l'estensione XML Parser legacy. Puoi usarla per analizzare XML e recuperare la stringa di errore, come segue:

analizza il file XML e recupera la stringa di errore usando xml_error_string() in PHP

$parser = xml_parser_create();
$xml_data = "<invalid xml>";
xml_parse($parser, $xml_data);

$error_code = xml_get_error_code($parser);
if ($error_code !== XML_ERROR_NONE) {
  $error_string = xml_error_string($error_code);
  echo "Error: $error_string";
}

xml_parser_free($parser);

Questo codice crea un parser XML con xml_parser_create(), tenta di analizzare la stringa malformata "<invalid xml>" (l'xml viene letto come nome di attributo senza valore) e verifica la presenza di errori. xml_get_error_code() restituisce un codice diverso da zero, xml_error_string() converte quel codice in testo, e lo script libera il parser con xml_parser_free().

Output:

Error: Attribute without value

Esempio 2: Individuare il punto esatto dell'errore

Una semplice stringa di errore raramente aiuta uno sviluppatore a correggere il documento. Combina xml_error_string() con le funzioni per il numero di riga e colonna per segnalare esattamente dove si è fermato il parser:

mostra il messaggio di errore insieme alla sua posizione

$parser = xml_parser_create();
$xml_data = "<book>\n  <title>Hi</titlex>\n</book>";

if (!xml_parse($parser, $xml_data, true)) {
  $code = xml_get_error_code($parser);
  printf(
    "Error %d: %s at line %d, column %d\n",
    $code,
    xml_error_string($code),
    xml_get_current_line_number($parser),
    xml_get_current_column_number($parser)
  );
}

xml_parser_free($parser);

Qui il tag di chiusura </titlex> non corrisponde all'apertura <title>, quindi il parsing fallisce alla riga 2. Le funzioni di posizione riportano il punto esatto:

Output:

Error 76: Mismatched tag at line 2, column 21

Il codice numerico esatto e la formulazione dipendono dalla versione di libxml in uso, ma xml_error_string() restituisce sempre il messaggio leggibile corrispondente al codice riportato da xml_get_error_code().

Esempio 2: Gestione degli errori SimpleXML (approccio moderno consigliato)

Se si utilizza la libreria SimpleXML, xml_error_string() non è applicabile. Usare invece libxml_use_internal_errors(true) e libxml_get_errors() per gestire i fallimenti di parsing:

Visualizzazione di un messaggio di errore del parser XML

libxml_use_internal_errors(true);

if (isset($_FILES["xml_file"])) {
  $xml = simplexml_load_file($_FILES["xml_file"]["tmp_name"]);
  if ($xml === false) {
    $errors = libxml_get_errors();
    foreach ($errors as $error) {
      echo "Error: " . $error->message;
    }
  } else {
    // process the XML file
  }
}

Questo codice abilita la gestione interna degli errori per SimpleXML, verifica se è stato caricato un file XML tramite l'array $_FILES e tenta di caricarlo. Se si verifica un errore durante il parsing, recupera i dettagli dell'errore con libxml_get_errors() e mostra il messaggio all'utente. Se non si verificano errori, il codice può elaborare il file XML come necessario.

Codici di errore comuni del parser XML

L'estensione XML Parser definisce costanti con nome per i casi "nessun errore" e di documento ben formato. L'unico valore su cui si può sempre contare è XML_ERROR_NONE (0), che indica che il parsing è riuscito. Alcuni codici bassi comuni e le stringhe restituite da xml_error_string() sono:

Attenzione: il numero intero effettivo restituito da un parsing reale, e la sua formulazione, sono prodotti dalla libreria libxml sottostante e variano tra le versioni di PHP/libxml — quindi passa sempre il valore live di xml_get_error_code() a xml_error_string() anziché assumere un numero fisso. Solo il controllo di successo XML_ERROR_NONE (0) è stabile tra le versioni.

Confrontare con XML_ERROR_NONE (anziché con uno 0 scritto direttamente) rende più chiaro lo scopo del controllo di successo.

Funzioni correlate

• xml_get_error_code() — restituisce il codice numerico da passare a xml_error_string().
• xml_parse() — esegue il parser e genera l'errore che poi viene descritto.
• xml_get_current_line_number() / xml_get_current_column_number() — localizzano l'errore nel sorgente.
• libxml_get_errors() — l'equivalente moderno usato con SimpleXML.

Conclusione

In questo articolo abbiamo discusso la funzione xml_error_string() di PHP e come può essere usata per recuperare una descrizione testuale di un errore del parser XML nei flussi di lavoro di parsing XML legacy. Abbiamo spiegato cosa fa la funzione, la sua sintassi e fornito esempi del suo utilizzo. Per le applicazioni PHP moderne che usano SimpleXML, si consiglia di usare libxml_use_internal_errors(true) e libxml_get_errors() per gestire i fallimenti di parsing, rendendo le applicazioni web più robuste e intuitive.

Esercizio