xml_parser_set_option()

La función xml_parser_set_option() es una función integrada de PHP que establece opciones de configuración en un analizador XML. Pertenece a la extensión XML Parser (Expat) heredada, que analiza XML en estilo SAX — disparando callbacks de eventos mientras lee — en lugar de construir un árbol en memoria como SimpleXML o DOM. Se llama después de xml_parser_create() pero antes de analizar, para controlar cómo el analizador trata las mayúsculas de nombres de etiquetas, el espacio en blanco y la codificación de caracteres.

Sintaxis

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

• $parser — el analizador devuelto por xml_parser_create(). Desde PHP 8.0 es un objeto XMLParser; en PHP 7 y versiones anteriores era un recurso.
• $option — una de las constantes de opción que se indican a continuación.
• $value — el valor a establecer para esa opción.

La función devuelve true en caso de éxito, o false si el analizador o la opción no son válidos.

Opciones disponibles

Leer el valor actual con xml_parser_get_option(). Establecer una opción después de que el análisis haya comenzado no tiene efecto, por lo que se debe configurar el analizador primero.

Por qué importa el plegado de mayúsculas

Esta es la opción a la que se recurrirá con más frecuencia. Por defecto, el analizador convierte a mayúsculas cada nombre de etiqueta, de modo que un elemento <note> llega al manejador como NOTE. Esto sorprende a quienes comparan nombres con cadenas en minúsculas. Desactivar el plegado de mayúsculas conserva los nombres exactamente tal como están escritos:

$parser = xml_parser_create();

// Default behaviour: case folding ON → names arrive upper-cased
xml_set_element_handler($parser,
    fn($p, $name, $attrs) => print("Start: $name\n"),
    fn($p, $name) => null
);
xml_parse($parser, "<note><to>Tove</to></note>", true);
xml_parser_free($parser);

Salida:

Start: NOTE
Start: TO

Establecer XML_OPTION_CASE_FOLDING en false hace que la misma entrada conserve su uso original de mayúsculas y minúsculas (note, to).

Un ejemplo completo

La extensión XML Parser está orientada a eventos: no ocurre nada hasta que se registran manejadores y se le suministran datos. Este ejemplo crea un analizador, establece dos opciones, registra manejadores de inicio/fin y analiza una cadena XML en línea — no se requiere ningún archivo externo, por lo que se puede ejecutar tal cual:

$parser = xml_parser_create();

// Keep the original tag case instead of upper-casing
xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, false);
// Drop elements that contain only whitespace
xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, true);

xml_set_element_handler(
    $parser,
    function ($parser, $name, $attrs) {
        echo "Start: $name\n";
    },
    function ($parser, $name) {
        echo "End: $name\n";
    }
);

$xml = "<note>\n  <to>Tove</to>\n  <from>Jani</from>\n</note>";
xml_parse($parser, $xml, true);

xml_parser_free($parser);

Salida:

Start: note
Start: to
End: to
Start: from
End: from
End: note

Como el plegado de mayúsculas está desactivado, los nombres de etiquetas conservan su escritura en minúsculas. La llamada a xml_set_element_handler() es lo que permite que xml_parse() emita estos eventos; sin manejadores registrados, el analizador leería el documento pero no produciría ninguna salida. Siempre hay que llamar a xml_parser_free() cuando se termina para liberar el analizador.

Cuándo utilizarla

Use xml_parser_set_option() únicamente cuando ya se esté trabajando con el analizador Expat de bajo nivel — típicamente para transmitir documentos XML muy grandes donde cargar todo el árbol en memoria no es deseable. Para la mayoría de las tareas cotidianas (leer configuración, consumir una respuesta de API) es preferible recurrir a SimpleXML, que es mucho más sencillo y no necesita ninguna de esta configuración.

Conclusión

xml_parser_set_option() configura el analizador XML heredado de estilo SAX — principalmente su comportamiento de plegado de mayúsculas, espacios en blanco y codificación. Establezca todas las opciones antes de llamar a xml_parse(), registre manejadores de elementos para que se emitan los eventos y libere el analizador después. Cuando se necesita un streaming detallado y eficiente en memoria, esta función proporciona ese control; de lo contrario, SimpleXML o DOM son la opción más sencilla.

Práctica