xml_set_processing_instruction_handler()

La función xml_set_processing_instruction_handler() establece una función definida por el usuario como manejador de instrucciones de procesamiento en un analizador XML. Pertenece a la extensión heredada xml (Expat / SAX) y se utiliza con el análisis basado en eventos, no con la biblioteca SimpleXML. Cada vez que el analizador encuentra una instrucción de procesamiento en el documento, llama a tu manejador para que puedas reaccionar ante ella — por ejemplo, para extraer directivas incrustadas o desencadenar una acción durante el análisis.

Esta página explica qué son las instrucciones de procesamiento, la sintaxis y los parámetros de la función, un ejemplo completo ejecutable, la firma del manejador, problemas habituales y las alternativas modernas que deberías utilizar hoy en día.

⚠️ Aviso de obsolescencia: La extensión xml fue marcada como obsoleta en PHP 8.0 y eliminada completamente en PHP 8.2. Esta función solo está disponible en PHP 7.4 y versiones anteriores. Para proyectos modernos, utiliza XMLReader o DOMDocument en su lugar.

¿Qué es una instrucción de procesamiento?

Una instrucción de procesamiento (PI) es un nodo XML especial que lleva instrucciones específicas de la aplicación al software que lee el documento. No es contenido de elemento — se sitúa entre el marcado. Una PI tiene dos partes: un objetivo (el nombre justo después de <?) y datos (todo hasta el ?> de cierre):

<?target data ?>

Por ejemplo, <?php-cache ttl="60" ?> tiene como objetivo php-cache y como datos ttl="60". La declaración XML <?xml version="1.0"?> parece una PI, pero se trata de forma especial y no activa este manejador.

Sintaxis

La sintaxis de la función xml_set_processing_instruction_handler() es la siguiente:

xml_set_processing_instruction_handler($parser, $handler)

Donde $parser es el recurso del analizador XML devuelto por xml_parser_create(), y $handler es un callable o una cadena que contiene el nombre de la función definida por el usuario que manejará las instrucciones de procesamiento. Pasa una cadena vacía ("") para eliminar un manejador previamente registrado.

Parámetros

Valor de retorno

Devuelve true en caso de éxito, o false si $parser no es un analizador XML válido.

La firma del manejador

Tu manejador se llama con exactamente tres argumentos:

function handler($parser, string $target, string $data): void

• $parser — el analizador que activó la llamada de retorno.
• $target — el objetivo de la PI (el nombre inmediatamente después de <?).
• $data — el resto de la PI, como una cadena sin procesar. Eres responsable de analizarla tú mismo; el analizador XML no la divide en atributos.

Ejemplos de uso

Veamos un ejemplo práctico del uso de xml_set_processing_instruction_handler() en PHP.

Ejemplo: Establecer una función manejadora de instrucciones de procesamiento

Supongamos que tienes una cadena XML que contiene instrucciones de procesamiento. Puedes usar la función xml_parser_create() para crear un nuevo analizador XML y, a continuación, establecer una función manejadora de instrucciones de procesamiento con xml_set_processing_instruction_handler(), de la siguiente manera:

function handle_processing_instruction($parser, $target, $data) {
    echo "Processing instruction found: $target - $data\n";
}

$xml_parser = xml_parser_create();
xml_set_processing_instruction_handler($xml_parser, "handle_processing_instruction");

$xml_data = '<?xml version="1.0"?><root><?PI target data?></root>';
if (!xml_parse($xml_parser, $xml_data)) {
    echo "XML parse error: " . xml_error_string(xml_get_error_code($xml_parser));
}

xml_parser_free($xml_parser);

Este código crea un nuevo analizador con xml_parser_create(). Luego establece una función personalizada para manejar las instrucciones de procesamiento. La función xml_parse() procesa la cadena XML y activa el manejador cuando encuentra una instrucción de procesamiento. El valor de retorno se comprueba para que xml_error_string() pueda informar de cualquier error de análisis. Finalmente, xml_parser_free() libera el recurso del analizador tras su uso.

En PHP 7.4, el programa imprime:

Processing instruction found: PI - target data

Ejemplo: Analizar los datos de una PI como opciones

Los datos de la PI llegan como una única cadena sin procesar, por lo que cualquier estructura interna es tuya para analizar. Un patrón habitual es tratar los datos como pares clave="valor":

function pi_handler($parser, $target, $data) {
    // Pull out key="value" pairs from the PI data
    preg_match_all('/(\w+)="([^"]*)"/', $data, $pairs, PREG_SET_ORDER);
    $options = [];
    foreach ($pairs as $pair) {
        $options[$pair[1]] = $pair[2];
    }
    echo "Target: $target\n";
    print_r($options);
}

$parser = xml_parser_create();
xml_set_processing_instruction_handler($parser, "pi_handler");
xml_parse($parser, '<root><?cache ttl="60" scope="page"?></root>');
xml_parser_free($parser);

En PHP 7.4, esto imprime:

Target: cache
Array
(
    [ttl] => 60
    [scope] => page
)

Manejadores relacionados

xml_set_processing_instruction_handler() es uno de una familia de configuradores de manejadores SAX. Normalmente se registran varios juntos en el mismo analizador:

• xml_set_element_handler() — etiquetas de apertura y cierre.
• xml_set_character_data_handler() — texto entre etiquetas.
• xml_set_default_handler() — cualquier cosa que no capture ningún otro manejador.
• xml_set_object() — enrutar los manejadores a métodos de objetos en lugar de funciones simples.

Problemas habituales

• La declaración XML no es una PI aquí. <?xml ... ?> es procesada por el analizador y nunca llega a tu manejador.
• Los datos no están analizados. $data es una única cadena. El analizador no dividirá el contenido clave="valor" en atributos — analízalo tú mismo.
• El manejador debe registrarse antes del análisis. Registra el manejador antes de llamar a xml_parse(), o las instrucciones tempranas se perderán.
• PHP 8.2+ no tiene la extensión xml. Todas las funciones xml_* han desaparecido; los ejemplos de esta página solo se ejecutan en PHP 7.4 o versiones anteriores.

Conclusión

En este artículo, hemos analizado la función xml_set_processing_instruction_handler() de PHP y cómo se puede utilizar para establecer un manejador de instrucciones de procesamiento para un analizador XML en la extensión heredada xml. Hemos explicado su sintaxis y proporcionado un ejemplo práctico. Ten en cuenta que, dado que la extensión xml fue eliminada en PHP 8.2, las aplicaciones modernas deben preferir XMLReader o DOMDocument para el procesamiento XML. Para bases de código heredadas que se ejecutan en PHP 7.4 o versiones anteriores, esta función sigue siendo una forma fiable de manejar instrucciones de procesamiento durante el análisis SAX.

Práctica