xml_parser_get_option()

La función xml_parser_get_option() lee el valor actual de una opción de configuración en un analizador XML creado con la extensión xml basada en Expat (la API heredada). Cada analizador mantiene un pequeño conjunto de opciones (plegado de mayúsculas, codificación de destino y omisión de espacios en blanco) que controlan cómo convierte el marcado sin procesar en eventos. Se establecen con xml_parser_set_option() y se leen con xml_parser_get_option().

En la práctica se recurre a esta función para confirmar la configuración de un analizador antes de comenzar el análisis; por ejemplo, para comprobar si el plegado de mayúsculas sigue activado o para registrar qué codificación de destino producirá el analizador. Es la contraparte de solo lectura del setter y nunca modifica el analizador.

Esta página cubre la firma de la función, las opciones que se pueden consultar (y sus valores predeterminados), un ejemplo ejecutable y las advertencias que conviene conocer, incluido el hecho de que Expat es una API de bajo nivel a la que la mayoría de los proyectos ya no recurre directamente.

Sintaxis

xml_parser_get_option(XMLParser $parser, int $option): string|int|bool

$parser es el identificador del analizador devuelto por xml_parser_create() (desde PHP 8.0 es un objeto XMLParser en lugar de un resource). $option es una de las constantes XML_OPTION_* que se describen a continuación. El tipo de retorno depende de la opción: un booleano para los indicadores de activar/desactivar, un entero para XML_OPTION_SKIP_TAGSTART y una cadena para XML_OPTION_TARGET_ENCODING.

Opciones disponibles

Consultar una opción desconocida devuelve false.

Ejemplos

Leer una sola opción

Esto crea un analizador, desactiva el plegado de mayúsculas y luego vuelve a leer la opción. Como se devuelve false, el mensaje indica "disabled":

<?php
$parser = xml_parser_create();
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);

$caseFolding = xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING);
echo "Case folding is " . ($caseFolding ? "enabled" : "disabled") . ".\n";

Salida:

Case folding is disabled.

Inspeccionar valores predeterminados y confirmar cambios

Un analizador recién creado ya tiene valores predeterminados razonables. Leerlos antes y después de una llamada set es una buena forma de verificar que la configuración surtió efecto:

<?php
$parser = xml_parser_create();

// Defaults on a brand-new parser.
echo "Default case folding: ";
var_dump(xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING));   // bool(true)
echo "Default encoding: ";
var_dump(xml_parser_get_option($parser, XML_OPTION_TARGET_ENCODING)); // string(5) "UTF-8"

// Change two options, then confirm them.
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, true);

printf("Case folding now: %s\n", xml_parser_get_option($parser, XML_OPTION_CASE_FOLDING) ? "on" : "off");
printf("Skip whitespace:  %s\n", xml_parser_get_option($parser, XML_OPTION_SKIP_WHITE) ? "on" : "off");

Salida:

Default case folding: bool(true)
Default encoding: string(5) "UTF-8"
Case folding now: off
Skip whitespace:  on

Establezca sus opciones primero, verifíquelas con xml_parser_get_option() si lo desea y solo entonces alimente datos a xml_parse(). Una vez iniciado el análisis, ya no está permitido cambiar las opciones de plegado de mayúsculas o codificación.

Notas y advertencias

• Solo lee. Esta función nunca muta el analizador. Para cambiar una opción, use xml_parser_set_option().
• Devuelve tipos mixtos. Trate el resultado según la opción: un indicador bool, un int para SKIP_TAGSTART o una cadena para la codificación. No asuma un booleano para cada opción.
• Expat es de bajo nivel y está desactualizado. La extensión xml (Expat) es anterior a las API modernas. A menos que necesite específicamente un análisis basado en eventos ("SAX") de documentos muy grandes, SimpleXML o DOM suelen ser más fáciles y seguros. Tenga en cuenta que XML_OPTION_CASE_FOLDING está activado por defecto (true), lo que es la sorpresa clásica: los nombres de elementos llegan en mayúsculas a menos que lo desactive.
• Libere el analizador cuando termine. Aunque PHP libera el objeto XMLParser automáticamente, puede llamar a xml_parser_free() para liberarlo explícitamente.

Conclusión

xml_parser_get_option() es la mitad getter del par de opciones del analizador Expat: devuelve el valor actual de XML_OPTION_CASE_FOLDING, XML_OPTION_TARGET_ENCODING, XML_OPTION_SKIP_WHITE o XML_OPTION_SKIP_TAGSTART sin cambiar nada. Úsela para confirmar la configuración de un analizador antes de llamar a xml_parse(). Para código nuevo que no necesite análisis SAX de bajo nivel, prefiera SimpleXML o la extensión DOM.

Práctica