xml_set_object()

La función xml_set_object() es una función integrada de PHP que establece el objeto al que deben aplicarse las funciones manejadoras de un analizador XML. Forma parte de la extensión heredada XML Parser. Al llamarla, el analizador deja de tratar los nombres que se pasan a funciones como xml_set_element_handler() como funciones globales y los trata como métodos del objeto proporcionado.

Esta página explica qué hace la función, su firma y parámetros, un ejemplo completo y ejecutable, los errores comunes y cómo se relaciona con el resto de la API de XML Parser.

Nota: xml_set_object() pertenece a la extensión heredada XML Parser (Expat) y está obsoleta a partir de PHP 8.4; en su lugar, pase un callable de método adecuado (p. ej. [$object, 'method']) directamente a las funciones xml_set_*_handler(). Para código nuevo, es preferible usar SimpleXML o DOMDocument, que modelan el documento como objetos directamente en lugar de usar manejadores de callback.

Por qué usarla

Sin xml_set_object(), cada manejador registrado debe ser una función independiente (o un par de cadena y método estático). Esto dificulta compartir estado entre manejadores y lleva a recurrir a variables globales.

Al vincular el analizador a un objeto, se puede:

• Mantener el estado de análisis (una pila, un contador, el documento en construcción) en propiedades del objeto.
• Registrar nombres de método simples como manejadores y que se resuelvan sobre ese objeto.
• Encapsular un analizador completo como una clase reutilizable.

Esta es la forma idiomática de envolver la API procedural de Expat en código orientado a objetos.

Sintaxis

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

Parámetros

Valor de retorno

Devuelve true en caso de éxito y false en caso de error. (A partir de PHP 8.0, $parser es una instancia de XMLParser; en PHP 7 y anteriores era un resource.)

El orden importa: llame a xml_set_object() antes de registrar manejadores como xml_set_element_handler() o xml_set_character_data_handler(). Los nombres de manejadores registrados después de establecer el objeto se buscan en dicho objeto.

Ejemplo: vincular un analizador a un objeto

Suponga que tiene una cadena XML para analizar con la extensión XML Parser. Cree un analizador con xml_parser_create(), vincúlelo a un objeto manejador con xml_set_object() y, a continuación, registre los manejadores de elementos por nombre de 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);

Salida:

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

Los nombres de elementos llegan en mayúsculas de forma predeterminada, porque el plegado de mayúsculas está activado a menos que se desactive con xml_parser_set_option(). El primer parámetro de cada manejador es el propio analizador, no el objeto vinculado — dentro del método ya se dispone de $this, por lo que ese primer argumento rara vez se utiliza.

Ejemplo: acumular estado en el objeto

El verdadero beneficio es el estado compartido. Aquí el objeto mantiene una profundidad acumulada para imprimir el árbol con formato — algo que requeriría una variable global sin 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);

Salida:

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

Errores comunes

• Establezca el objeto primero. Registrar un manejador antes de xml_set_object() resuelve el nombre como una función global, no como un método.
• Los nombres de manejadores son cadenas. Pase el nombre del método ("open"), no un array callable. El vínculo es lo que indica al analizador que busque el nombre en el objeto.
• Libere el analizador. Llame a xml_parser_free() cuando haya terminado (las versiones modernas de PHP también limpian automáticamente).
• Es heredada. Los proyectos nuevos deben usar SimpleXML o DOMDocument en su lugar.

Funciones relacionadas

• xml_parser_create() — crea el analizador al que se vincula.
• xml_set_element_handler() — registra manejadores de etiquetas de apertura y cierre.
• xml_set_character_data_handler() — maneja el texto entre etiquetas.
• xml_parse() — alimenta XML al analizador.
• xml_parser_free() — libera el analizador.

Conclusión

xml_set_object() vincula un analizador XML a un objeto de modo que los nombres de manejadores registrados posteriormente se resuelvan como métodos de ese objeto. El beneficio es la encapsulación: el estado de análisis reside en propiedades del objeto en lugar de en variables globales, y un analizador completo puede empaquetarse como una clase. Recuerde llamarla antes de registrar los manejadores, y que la función forma parte de la extensión Expat heredada — para código nuevo, opte por SimpleXML o DOMDocument.

Práctica