xml_parser_free()

A função xml_parser_free() é uma função nativa do PHP que libera a memória associada a um parser XML. Ela pertence à extensão XML (Expat / SAX) do PHP e é chamada para liberar um parser após a leitura de um documento.

Um parser SAX criado com xml_parser_create() lê um documento como um fluxo de eventos — uma tag de abertura, dados de caracteres, uma tag de fechamento — e aciona os seus handlers de callback para cada um. Como o parser mantém buffers internos e referências a esses handlers, chamar xml_parser_free() ao final do processamento quebra essas referências para que a memória possa ser recuperada.

Esta página explica o que a função faz, quando você realmente precisa dela e mostra um exemplo completo e executável de análise.

Sintaxe

xml_parser_free(XMLParser $parser): bool

Valor de retorno — retorna true em caso de sucesso, ou false se $parser não se referir a um parser válido.

Nota de versão: No PHP 8.0 e posterior, xml_parser_create() retorna um objeto XMLParser em vez de um recurso. Chamar xml_parser_free() não é mais estritamente necessário — o parser é liberado automaticamente quando o objeto sai do escopo e é coletado pelo garbage collector. A função é mantida para compatibilidade com versões anteriores e ainda é uma boa prática em scripts de longa duração onde você deseja liberar a memória imediatamente.

Quando você deve chamá-la?

• Processos de longa duração (workers de fila, daemons, jobs em lote via CLI) que criam muitos parsers — liberar cada um mantém a memória estável em vez de deixá-la crescer até o fim do script.
• Arquivos XML grandes ou numerosos, onde manter buffers do parser por mais tempo do que o necessário desperdiça RAM.
• Antes do PHP 8.0, onde o parser era um recurso e não estava vinculado à limpeza baseada em escopo, portanto liberá-lo explicitamente era a única maneira confiável de recuperar memória no meio do script.

Para um script curto e único que termina imediatamente após a análise, a diferença é desprezível — o PHP libera tudo no encerramento de qualquer forma.

Exemplo completo

O trecho abaixo cria um parser, registra handlers, analisa uma string XML e então libera o parser. Os handlers coletam cada título de <book> em um array.

<?php
$xml = <<<XML
<?xml version="1.0"?>
<library>
  <book>PHP Basics</book>
  <book>Mastering XML</book>
</library>
XML;

$titles  = [];
$current = false;

// Fired on every opening tag
function startTag($parser, $name, $attrs) {
    global $current;
    $current = ($name === "BOOK"); // tag names are upper-cased by default
}

// Fired on every closing tag
function endTag($parser, $name) {
    global $current;
    $current = false;
}

// Fired for the text between tags
function charData($parser, $data) {
    global $current, $titles;
    if ($current && trim($data) !== "") {
        $titles[] = trim($data);
    }
}

$parser = xml_parser_create();
xml_set_element_handler($parser, "startTag", "endTag");
xml_set_character_data_handler($parser, "charData");

// Parse the whole document in one call (final argument = true)
xml_parse($parser, $xml, true);

// Release the parser's memory now that we are done
xml_parser_free($parser);

print_r($titles);

Saída:

Array
(
    [0] => PHP Basics
    [1] => Mastering XML
)

Algumas coisas que vale a pena notar:

• Os nomes dos elementos chegam em letras maiúsculas por padrão (BOOK, não book). Desative isso com xml_parser_set_option() e o flag XML_OPTION_CASE_FOLDING se precisar manter a capitalização original.
• O ciclo de vida é sempre o mesmo: criar → definir handlers → analisar → liberar. Os handlers xml_set_* (elemento e dados de caracteres) fazem o trabalho real; xml_parser_free() simplesmente fecha o ciclo.
• Após chamar xml_parser_free(), o identificador $parser não pode mais ser usado — crie um novo se precisar analisar outro documento.

Conclusão

xml_parser_free() libera a memória mantida por um parser Expat/SAX criado com xml_parser_create(). Use-a junto com xml_parser_create(), seus handlers xml_set_* e xml_parse() para gerenciar a memória de forma limpa. A partir do PHP 8.0, o parser é liberado automaticamente quando sai do escopo, mas chamar a função explicitamente continua sendo um hábito sensato em scripts de longa duração.

Prática