xml_parser_get_option()

A função xml_parser_get_option() lê o valor atual de uma opção de configuração em um parser XML criado com a extensão xml legada baseada em Expat. Cada parser mantém um pequeno conjunto de opções (dobragem de maiúsculas, codificação de destino e ignorar espaços em branco) que controlam como ele transforma a marcação bruta em eventos. Você as define com xml_parser_set_option(); você as lê de volta com xml_parser_get_option().

Na prática, você a utiliza para confirmar a configuração de um parser antes de iniciar a análise — por exemplo, para verificar se a dobragem de maiúsculas ainda está ativa ou para registrar qual codificação de destino um parser produzirá. É o complemento somente leitura do setter e nunca altera o parser.

Esta página abrange a assinatura da função, as opções que você pode consultar (e seus padrões), um exemplo executável e as armadilhas que vale conhecer — incluindo o fato de que o Expat é uma API de baixo nível que a maioria dos projetos não utiliza mais diretamente.

Sintaxe

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

$parser é o identificador do parser retornado por xml_parser_create() (desde o PHP 8.0, este é um objeto XMLParser em vez de um resource). $option é uma das constantes XML_OPTION_* abaixo. O tipo de retorno depende da opção: um boolean para os sinalizadores ligado/desligado, um inteiro para XML_OPTION_SKIP_TAGSTART e uma string para XML_OPTION_TARGET_ENCODING.

Opções disponíveis

Consultar uma opção desconhecida retorna false.

Exemplos

Lendo uma única opção

Isso cria um parser, desativa a dobragem de maiúsculas e depois lê a opção de volta. Como false é retornado, a mensagem informa "desativada":

<?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";

Saída:

Case folding is disabled.

Inspecionando padrões e confirmando alterações

Um parser recém-criado já possui padrões sensatos. Lê-los antes e depois de uma chamada set é uma boa maneira de verificar se sua configuração teve efeito:

<?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");

Saída:

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

Defina suas opções primeiro, verifique-as com xml_parser_get_option() se quiser, e somente então alimente os dados para xml_parse(). Depois que a análise começa, alterar as opções de dobragem de maiúsculas ou codificação não é mais permitido.

Notas e armadilhas

• Apenas leitura. Esta função nunca muta o parser. Para alterar uma opção, use xml_parser_set_option().
• Retorna tipos mistos. Trate o resultado por opção: um sinalizador bool, um int para SKIP_TAGSTART ou uma string para a codificação. Não assuma um boolean para todas as opções.
• O Expat é de baixo nível e desatualizado. A extensão xml (Expat) é anterior às APIs modernas. A menos que você precise especificamente de análise baseada em eventos ("SAX") de documentos muito grandes, SimpleXML ou DOM geralmente são mais fáceis e seguros. Note que XML_OPTION_CASE_FOLDING com padrão true é a surpresa clássica: os nomes de elementos chegam em maiúsculas a menos que você desative isso.
• Libere o parser quando terminar. Embora o PHP libere o objeto XMLParser por conta própria, você pode chamar xml_parser_free() para liberá-lo explicitamente.

Conclusão

xml_parser_get_option() é a metade getter do par de opções do parser Expat: retorna o valor atual de XML_OPTION_CASE_FOLDING, XML_OPTION_TARGET_ENCODING, XML_OPTION_SKIP_WHITE ou XML_OPTION_SKIP_TAGSTART sem alterar nada. Use-a para confirmar a configuração de um parser antes de chamar xml_parse(). Para novo código que não precisa de análise SAX de baixo nível, prefira SimpleXML ou a extensão DOM.

Prática