xml_parser_set_option()

A função xml_parser_set_option() é uma função interna do PHP que define opções de configuração em um parser XML. Ela pertence à extensão legada XML Parser (Expat), que analisa XML no estilo SAX — disparando callbacks de eventos conforme lê — em vez de construir uma árvore na memória como o SimpleXML ou o DOM. Você a chama após xml_parser_create(), mas antes de analisar, para controlar como o parser trata maiúsculas/minúsculas em nomes de tags, espaços em branco e codificação de caracteres.

Sintaxe

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

• $parser — o parser retornado por xml_parser_create(). A partir do PHP 8.0, é um objeto XMLParser; no PHP 7 e versões anteriores era um resource.
• $option — uma das constantes de opção listadas abaixo.
• $value — o valor a ser definido para essa opção.

A função retorna true em caso de sucesso ou false se o parser ou a opção for inválido.

Opções disponíveis

Leia o valor atual com xml_parser_get_option(). Definir uma opção após o início da análise não tem efeito, portanto configure o parser antes de começar.

Por que a conversão de maiúsculas importa

Esta é a opção que você usará com mais frequência. Por padrão, o parser converte para maiúsculas todos os nomes de tags, portanto um elemento <note> chega ao seu handler como NOTE. Isso surpreende quem compara nomes com strings em minúsculas. Desativar a conversão de maiúsculas mantém os nomes exatamente como foram 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);

Saída:

Start: NOTE
Start: TO

Defina XML_OPTION_CASE_FOLDING como false e a mesma entrada mantém sua capitalização original (note, to).

Um exemplo completo

A extensão XML Parser é orientada a eventos: nada acontece até que você registre handlers e forneça dados. Este exemplo cria um parser, define duas opções, registra handlers de início/fim e analisa uma string XML inline — nenhum arquivo externo é necessário, portanto você pode executá-lo diretamente:

$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);

Saída:

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

Como a conversão de maiúsculas está desativada, os nomes das tags mantêm sua grafia em minúsculas. A chamada xml_set_element_handler() é o que permite que xml_parse() emita esses eventos; sem handlers registrados, o parser leria o documento, mas não produziria nenhuma saída. Sempre chame xml_parser_free() ao terminar para liberar o parser.

Quando utilizá-la

Use xml_parser_set_option() apenas quando você já estiver trabalhando com o parser Expat de baixo nível — tipicamente para processar documentos XML muito grandes em streaming, onde carregar a árvore inteira na memória é indesejável. Para a maioria das tarefas cotidianas (leitura de configuração, consumo de resposta de API), prefira o SimpleXML, que é muito mais simples e não precisa de nenhuma configuração desse tipo.

Conclusão

xml_parser_set_option() configura o parser XML legado no estilo SAX — principalmente seu comportamento de conversão de maiúsculas, espaços em branco e codificação. Defina todas as opções antes de chamar xml_parse(), registre handlers de elementos para que os eventos sejam emitidos e libere o parser depois. Quando você precisa de streaming eficiente em termos de memória e com controle granular, esta função oferece esse controle; caso contrário, SimpleXML ou DOM são as escolhas mais simples.

Prática