xml_parser_free()

The xml_parser_free() function is a PHP built-in function that frees the memory associated with an XML parser. It belongs to PHP's XML (Expat / SAX) extension and is called to release a parser once you are finished reading a document.

A SAX parser created with xml_parser_create() reads a document as a stream of events — a start tag, character data, an end tag — and triggers your callback handlers for each one. Because the parser holds internal buffers and references to those handlers, calling xml_parser_free() when parsing is done breaks those references so the memory can be reclaimed.

This page explains what the function does, when you actually need it, and shows a complete, runnable parsing example.

Syntax

xml_parser_free(XMLParser $parser): bool

Return value — returns true on success, or false if $parser does not refer to a valid parser.

Version note: In PHP 8.0 and later, xml_parser_create() returns an XMLParser object rather than a resource. Calling xml_parser_free() is no longer strictly required — the parser is freed automatically when the object goes out of scope and is garbage-collected. The function is kept for backward compatibility and is still good practice in long-running scripts where you want memory released immediately.

When should you call it?

• Long-running processes (queue workers, daemons, CLI batch jobs) that create many parsers — freeing each one keeps memory flat instead of letting it climb until the script ends.
• Large or numerous XML files, where holding parser buffers longer than necessary wastes RAM.
• Before PHP 8.0, where the parser was a resource and was not tied to scope-based cleanup, so freeing it explicitly was the only reliable way to reclaim memory mid-script.

For a short, one-off script that exits immediately after parsing, the difference is negligible — PHP releases everything on shutdown anyway.

Complete example

The snippet below creates a parser, registers handlers, parses an XML string, and then frees the parser. The handlers collect every <book> title into an 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);

Output:

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

A few things worth noting:

• Element names arrive upper-cased by default (BOOK, not book). Disable this with xml_parser_set_option() and the XML_OPTION_CASE_FOLDING flag if you need the original casing.
• The lifecycle is always the same: create → set handlers → parse → free. The xml_set_* handlers (element and character data) do the real work; xml_parser_free() simply closes out the cycle.
• After calling xml_parser_free(), the $parser handle is no longer usable — create a fresh one if you need to parse another document.

Conclusion

xml_parser_free() releases the memory held by an Expat/SAX parser created with xml_parser_create(). Pair it with xml_parser_create(), your xml_set_* handlers, and xml_parse() to manage memory cleanly. From PHP 8.0 onward the parser is freed automatically when it falls out of scope, but calling the function explicitly remains a sensible habit in long-running scripts.

Practice