xml_set_processing_instruction_handler()

A função xml_set_processing_instruction_handler() define uma função personalizada como handler para instruções de processamento em um parser XML. Ela pertence à extensão legada xml (Expat / SAX) e é usada com parsing baseado em eventos, não com a biblioteca SimpleXML. Sempre que o parser encontra uma instrução de processamento no documento, ele chama o seu handler para que você possa reagir a ela — por exemplo, para extrair diretivas incorporadas ou acionar uma ação durante o parse.

Esta página aborda o que são instruções de processamento, a sintaxe e os parâmetros da função, um exemplo completo executável, a assinatura do handler, armadilhas comuns e as alternativas modernas que você deve utilizar atualmente.

⚠️ Aviso de Depreciação: A extensão xml foi depreciada no PHP 8.0 e completamente removida no PHP 8.2. Esta função só está disponível no PHP 7.4 e versões anteriores. Para projetos modernos, use XMLReader ou DOMDocument.

O que é uma Instrução de Processamento?

Uma instrução de processamento (PI) é um nó XML especial que carrega instruções específicas de aplicação para qualquer software que leia o documento. Ela não é conteúdo de elemento — fica entre a marcação. Uma PI tem duas partes: um alvo (o nome logo após <?) e dados (tudo até o ?> de fechamento):

<?target data ?>

Por exemplo, <?php-cache ttl="60" ?> tem o alvo php-cache e os dados ttl="60". A declaração XML <?xml version="1.0"?> parece uma PI, mas é tratada de forma especial e não aciona este handler.

Sintaxe

A sintaxe da função xml_set_processing_instruction_handler() é a seguinte:

xml_set_processing_instruction_handler($parser, $handler)

Onde $parser é o recurso de parser XML retornado por xml_parser_create(), e $handler é um callable ou uma string contendo o nome da função definida pelo usuário que tratará as instruções de processamento. Passe uma string vazia ("") para remover um handler previamente registrado.

Parâmetros

Valor de Retorno

Retorna true em caso de sucesso, ou false se $parser não for um parser XML válido.

A Assinatura do Handler

Seu handler é chamado com exatamente três argumentos:

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

• $parser — o parser que acionou o callback.
• $target — o alvo da PI (o nome imediatamente após <?).
• $data — o restante da PI, como uma string bruta. Você é responsável por analisá-la; o parser XML não a divide em atributos.

Exemplos de Uso

Vejamos um exemplo prático do uso de xml_set_processing_instruction_handler() em PHP.

Exemplo: Definindo uma Função Handler para Instrução de Processamento

Suponha que você tenha uma string XML contendo instruções de processamento. Você pode usar a função xml_parser_create() para criar um novo parser XML e, em seguida, definir uma função handler de instrução de processamento usando xml_set_processing_instruction_handler(), assim:

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 cria um novo parser usando xml_parser_create(). Em seguida, define uma função personalizada para tratar instruções de processamento. A função xml_parse() processa a string XML, acionando o handler quando encontra uma instrução de processamento. O valor de retorno é verificado para que xml_error_string() possa reportar erros de parsing. Por fim, xml_parser_free() libera o recurso do parser após o uso.

No PHP 7.4, o programa imprime:

Processing instruction found: PI - target data

Exemplo: Analisando Dados de PI em Opções

Os dados da PI chegam como uma única string bruta, portanto qualquer estrutura interna é sua para analisar. Um padrão comum é tratar os dados como pares chave="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);

No PHP 7.4, isso imprime:

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

Handlers Relacionados

xml_set_processing_instruction_handler() é um dos handlers da família de setters SAX. Normalmente você registra vários juntos no mesmo parser:

• xml_set_element_handler() — tags de abertura e fechamento.
• xml_set_character_data_handler() — texto entre as tags.
• xml_set_default_handler() — qualquer coisa que nenhum outro handler capture.
• xml_set_object() — roteie handlers para métodos de objetos em vez de funções simples.

Armadilhas Comuns

• A declaração XML não é uma PI aqui. <?xml ... ?> é consumido pelo parser e nunca chega ao seu handler.
• Os dados não são analisados. $data é uma única string. O parser não dividirá o conteúdo chave="valor" em atributos para você — analise-o você mesmo.
• Handler definido antes do parsing. Registre o handler antes de chamar xml_parse(), caso contrário as primeiras instruções serão perdidas.
• PHP 8.2+ não possui a extensão xml. Todas as funções xml_* foram removidas; os exemplos nesta página só funcionam no PHP 7.4 ou anteriores.

Conclusão

Neste artigo, discutimos a função xml_set_processing_instruction_handler() do PHP e como ela pode ser usada para definir um handler de instrução de processamento para um parser XML na extensão legada xml. Explicamos sua sintaxe e fornecemos um exemplo prático. Observe que, como a extensão xml foi removida no PHP 8.2, as aplicações modernas devem preferir XMLReader ou DOMDocument para o processamento XML. Para bases de código legadas que rodam no PHP 7.4 ou anteriores, esta função permanece uma maneira confiável de tratar instruções de processamento durante o parsing SAX.

Prática