xml_set_object()

A função xml_set_object() é uma função nativa do PHP que define o objeto ao qual as funções manipuladoras de um parser XML devem ser aplicadas. Ela faz parte da extensão legada XML Parser. Ao chamá-la, o parser deixa de tratar os nomes passados para funções como xml_set_element_handler() como funções globais e passa a tratá-los como métodos do objeto fornecido.

Esta página explica o que a função faz, sua assinatura e parâmetros, um exemplo completo executável, os erros comuns e como ela se relaciona com o restante da API do XML Parser.

Nota: xml_set_object() pertence à extensão legada XML Parser (Expat) e está descontinuada a partir do PHP 8.4 — em vez disso, passe um callable de método adequado (por exemplo, [$object, 'method']) diretamente para as funções xml_set_*_handler(). Para código novo, prefira SimpleXML ou DOMDocument, que modelam o documento como objetos diretamente, em vez de usar callbacks.

Por que usar

Sem xml_set_object(), cada manipulador registrado precisa ser uma função independente (ou um par de string e método estático). Isso dificulta o compartilhamento de estado entre manipuladores — você acaba recorrendo a variáveis globais.

Ao vincular o parser a um objeto, você pode:

• Manter o estado do parsing (uma pilha, um contador, o documento em construção) em propriedades do objeto.
• Registrar nomes de métodos simples como manipuladores e fazê-los ser resolvidos no objeto.
• Encapsular um parser inteiro como uma classe reutilizável.

Esta é a forma idiomática de encapsular a API procedural Expat em código orientado a objetos.

Sintaxe

xml_set_object(XMLParser $parser, object $object): bool

Parâmetros

Valor de retorno

Retorna true em caso de sucesso e false em caso de falha. (A partir do PHP 8.0, $parser é uma instância de XMLParser; no PHP 7 e anteriores, era um resource.)

A ordem importa: chame xml_set_object() antes de registrar manipuladores como xml_set_element_handler() ou xml_set_character_data_handler(). Os nomes de manipuladores registrados após a definição do objeto são pesquisados nesse objeto.

Exemplo: vinculando um parser a um objeto

Suponha que você tenha uma string XML para analisar com a extensão XML Parser. Crie um parser com xml_parser_create(), vincule-o a um objeto manipulador com xml_set_object() e registre os manipuladores de elementos pelo nome do método:

class MyHandler {
    function startElement($parser, $name, $attribs) {
        echo "Start element: $name\n";
    }
    function endElement($parser, $name) {
        echo "End element: $name\n";
    }
}

$handler    = new MyHandler();
$xmlParser  = xml_parser_create();
xml_set_object($xmlParser, $handler);
xml_set_element_handler($xmlParser, "startElement", "endElement");

$xmlData = '<root><item>Test</item></root>';
xml_parse($xmlParser, $xmlData, true);
xml_parser_free($xmlParser);

Saída:

Start element: ROOT
Start element: ITEM
End element: ITEM
End element: ROOT

Os nomes dos elementos chegam em maiúsculas por padrão, porque o dobramentos de maiúsculas está ativado a menos que você o desative com xml_parser_set_option(). O primeiro parâmetro de cada manipulador é o próprio parser, não o objeto vinculado — dentro do método você já tem $this, portanto esse primeiro argumento raramente é usado.

Exemplo: acumulando estado no objeto

O benefício real é o estado compartilhado. Aqui o objeto mantém uma profundidade acumulada para que possa imprimir a árvore de forma legível — algo que precisaria de uma variável global sem xml_set_object():

class TreePrinter {
    private int $depth = 0;

    function open($parser, $name) {
        echo str_repeat("  ", $this->depth) . "<$name>\n";
        $this->depth++;
    }
    function close($parser, $name) {
        $this->depth--;
        echo str_repeat("  ", $this->depth) . "</$name>\n";
    }
}

$parser = xml_parser_create();
xml_set_object($parser, new TreePrinter());
xml_set_element_handler($parser, "open", "close");
xml_parse($parser, "<a><b><c/></b></a>", true);
xml_parser_free($parser);

Saída:

<A>
  <B>
    <C>
    </C>
  </B>
</A>

Erros comuns

• Defina o objeto primeiro. Registrar um manipulador antes de xml_set_object() resolve o nome como uma função global, não como um método.
• Nomes de manipuladores são strings. Passe o nome do método ("open"), não um array callable. O vínculo é o que diz ao parser para pesquisar o nome no objeto.
• Libere o parser. Chame xml_parser_free() ao terminar (o PHP moderno também limpa automaticamente).
• É uma funcionalidade legada. Novos projetos devem usar SimpleXML ou DOMDocument.

Funções relacionadas

• xml_parser_create() — cria o parser ao qual você se vincula.
• xml_set_element_handler() — registra manipuladores de tags de abertura/fechamento.
• xml_set_character_data_handler() — trata texto entre tags.
• xml_parse() — envia XML ao parser.
• xml_parser_free() — libera o parser.

Conclusão

xml_set_object() vincula um parser XML a um objeto para que os nomes de manipuladores registrados posteriormente sejam resolvidos como métodos desse objeto. O benefício é o encapsulamento: o estado do parsing fica nas propriedades do objeto em vez de variáveis globais, e um parser inteiro pode ser empacotado como uma classe. Lembre-se de chamá-la antes de registrar os manipuladores, e que a função faz parte da extensão Expat legada — para código novo, prefira SimpleXML ou DOMDocument.

Prática