Skip to content

21. Processamento de documentos XML

Os serviços web que escrevemos até aqui trocam dados JSON. O XML (eXtensible Markup Language) foi por muito tempo o formato de troca mais utilizado e ainda é encontrado com frequência: serviços web SOAP, feeds RSS, arquivos de configuração, documentos de escritório (um arquivo [.odt] ou [.docx] é um arquivo compactado de arquivos XML). O PHP oferece duas APIs para trabalhar com ele:

  • [SimpleXML]: uma API muito simples, em que os elementos do documento se tornam propriedades de objeto;
  • [DOM] (Document Object Model): a API padrão do W3C, mais completa e que também permite modificar um documento. O PHP 8.4 introduziu uma nova versão, no namespace [Dom], compatível com o padrão web atual.

Os scripts deste capítulo estão na pasta [scripts-console/xml]:

1
2
3
4
scripts-console/xml
├── data.xml
├── dom-01.php
└── simplexml-01.php

21.1. O documento em estudo

Consideramos o seguinte arquivo XML [data.xml]:

<?xml version="1.0" encoding="UTF-8"?>

<tribe>
    <teacher>
        <person gender="M">
            <lastName>dupont</lastName>
            <firstName>jean</firstName>
            <age>28</age>
            this is a comment
        </person>
        <section>27</section>
    </teacher>
    <student>
        <person gender="F">
            <lastName>martin</lastName>
            <firstName>charline</firstName>
            <age>22</age>
        </person>
        <course>dess IAIE</course>
    </student>
</tribe>

Um documento XML é uma árvore de elementos:

  • linha 1: o prólogo, que especifica a versão do XML e a codificação de caracteres do documento;
  • linhas 3–21: o elemento raiz [tribe]. Um documento XML tem exatamente uma raiz;
  • linhas 4–12: o elemento [teacher], filho de [tribe]. Ele tem dois filhos, [person] e [section];
  • linha 5: o elemento [person] tem um atributo [gender] com o valor [M];
  • linha 9: um elemento pode conter tanto outros elementos quanto texto;
  • linhas 13–20: o elemento [student], que tem a mesma estrutura que [teacher].

21.2. Processamento com SimpleXML

Analisamos este documento com o seguinte script [simplexml-01.php]:

<?php

declare(strict_types=1);

// o arquivo XML a ser usado
const FILE_NAME = "data.xml";

// carregamento do documento XML
$xml = simplexml_load_file(FILE_NAME);
if ($xml === false) {
    print "The file [" . FILE_NAME . "] could not be used\n";
    exit(1);
}
// exibição do documento
print_r($xml);
// o atributo [gender] da pessoa docente
print_r($xml->teacher->person['gender']);
// valores de elementos e atributos, convertidos em strings
$lastName = (string) $xml->teacher->person->lastName;
print "lastName=$lastName\n";
$gender = (string) $xml->teacher->person['gender'];
print "gender=$gender\n";
$course = (string) $xml->student->course;
print "course=$course\n";
// existência de um elemento
print "isset(lastName)=" . var_export(isset($xml->teacher->person->lastName), true) . "\n";
print "isset(xx)=" . var_export(isset($xml->teacher->person->xx), true) . "\n";
// uma conversão para inteiro
$age = (int) $xml->student->person->age;
print "age of the student=$age\n";
// iteração sobre todos os elementos <person> do documento com XPath
foreach ($xml->xpath('//person') as $person) {
    print "person: {$person->firstName} {$person->lastName} ({$person['gender']})\n";
}

Comentários

  • linha 6: O nome do arquivo XML é uma constante. O script é executado em sua própria pasta, a de [data.xml];
  • Linha 9: A função [simplexml_load_file] carrega o documento e retorna um objeto do tipo [SimpleXMLElement], que representa o elemento raiz [tribe]. Em caso de erro (arquivo ausente, XML malformado), ela retorna [false], o que testamos na linha 10;
  • linha 15: exibição do documento. O [print_r] mostra como o [SimpleXML] enxerga a árvore XML;
  • linha 17: os elementos filhos são acessados como propriedades ([$xml->teacher->person]) e os atributos como chaves de array ([['gender']]). Observe que a raiz [tribe] não aparece no código: [$xml] já é esse elemento;
  • linha 19: [$xml->teacher->person->lastName] não é uma string, mas um objeto [SimpleXMLElement]. A conversão [(string)] fornece seu texto. Com [declare(strict_types=1)], é melhor fazer essa conversão explicitamente antes de passar o valor a uma função que espera uma string;
  • Linha 21: o valor do atributo [gender];
  • Linhas 26–27: [isset] determina se um elemento existe. O script do PHP 7 exibia o resultado booleano com [print], que retorna [1] para [true] e uma string vazia para [false]. Usamos [var_export], que exibe [true] ou [false];
  • linha 29: a conversão [(int)] retorna o valor inteiro do texto do elemento;
  • linha 32: o método [xpath] avalia uma expressão XPath. A expressão [//person] refere-se a todos os elementos [person] do documento, independentemente do nível. Isso retorna um array de [SimpleXMLElement].

Saída no console

> php simplexml-01.php
SimpleXMLElement Object
(
    [teacher] => SimpleXMLElement Object
        (
            [person] => SimpleXMLElement Object
                (
                    [@attributes] => Array
                        (
                            [gender] => M
                        )

                    [lastName] => dupont
                    [firstName] => jean
                    [age] => 28
                )

            [section] => 27
        )

    [student] => SimpleXMLElement Object
        (
            [person] => SimpleXMLElement Object
                (
                    [@attributes] => Array
                        (
                            [gender] => F
                        )

                    [lastName] => martin
                    [firstName] => charline
                    [age] => 22
                )

            [course] => dess IAIE
        )

)
SimpleXMLElement Object
(
    [0] => M
)
lastName=dupont
gender=M
course=dess IAIE
isset(lastName)=true
isset(xx)=false
age of the student=22
person: jean dupont (M)
person: charline martin (F)
  • Linhas 2–38: o documento XML na forma de um objeto [SimpleXMLElement]. Observe que o texto [this is a comment] não aparece: o [print_r] mostra apenas os elementos e atributos;
  • linhas 39–42: um atributo também é um objeto [SimpleXMLElement];
  • linhas 43–48: os valores lidos do documento;
  • linhas 49–50: a travessia XPath das duas pessoas.

21.3. Processamento com a nova API DOM do PHP 8.4

A partir do PHP 8.4, o namespace [Dom] oferece uma nova API DOM: a classe [Dom\XMLDocument] para documentos XML e a classe [Dom\HTMLDocument] para documentos HTML5. Ela é um substituto melhor para a antiga classe [DOMDocument] (que continua disponível): segue o padrão DOM atual e fornece os métodos [querySelector] e [querySelectorAll] familiares aos desenvolvedores JavaScript. Esses métodos permitem buscar elementos usando seletores CSS.

O script [dom-01.php] usa o mesmo documento:

<?php

declare(strict_types=1);

// o mesmo documento usado com a nova API DOM do PHP 8.4

use Dom\XMLDocument;

// o arquivo XML a ser usado
const FILE_NAME = "data.xml";

try {
    // carregamento do documento XML
    $document = XMLDocument::createFromFile(FILE_NAME);
} catch (Throwable $ex) {
    print "The file [" . FILE_NAME . "] could not be used: {$ex->getMessage()}\n";
    exit(1);
}
// o elemento raiz
print "root=" . $document->documentElement->tagName . "\n";
// a 1ª pessoa docente, encontrada com um seletor CSS
$person = $document->querySelector('teacher > person');
print "lastName=" . $person->querySelector('lastName')->textContent . "\n";
print "gender=" . $person->getAttribute('gender') . "\n";
print "course=" . $document->querySelector('student > course')->textContent . "\n";
// um elemento ausente: querySelector retorna null
print "xx exists=" . var_export($person->querySelector('xx') !== null, true) . "\n";
// todas as pessoas do documento
foreach ($document->querySelectorAll('person') as $person) {
    // o operador nullsafe ?-> protege contra um elemento ausente
    $firstName = $person->querySelector('firstName')?->textContent ?? '?';
    $lastName = $person->querySelector('lastName')?->textContent ?? '?';
    print "person: $firstName $lastName ({$person->getAttribute('gender')})\n";
}
// modificação do documento: alteramos o conteúdo do elemento <section> do professor
$section = $document->querySelector('teacher > section');
$section->textContent = "26";
// o documento modificado, como texto XML
print $document->saveXml($document->querySelector('teacher')) . "\n";

Comentários

  • linha 7: a classe [XMLDocument] do namespace [Dom];
  • Linha 14: O método estático [createFromFile] carrega o documento. Diferentemente de [simplexml_load_file], ele lança uma exceção se ocorrer um erro;
  • linha 20: a propriedade [documentElement] é o elemento raiz; [tagName] é o seu nome;
  • linha 22: o seletor CSS [teacher > person] refere-se a um elemento [person] que é filho direto de um elemento [teacher]. [querySelector] retorna o primeiro elemento correspondente, ou [null] se não houver nenhum;
  • linha 23: a propriedade [textContent] é o texto contido no elemento;
  • linha 24: o valor de um atributo;
  • linha 27: um elemento ausente retorna [null];
  • linha 29: todos os elementos [person] do documento;
  • Linha 31: Se o elemento [firstName] estivesse ausente, [querySelector('firstName')] resultaria em [null]. O operador null-safe [?->] (PHP 8.0) então retorna [null] em vez de causar um erro, e o operador [??] substitui esse [null] por ['?'];
  • linha 37: a API DOM também permite modificar o documento: aqui, o texto do elemento [section] é alterado;
  • linha 39: [saveXml] retorna o texto XML do documento, ou de um de seus elementos se ele for passado como parâmetro.

Saída no console

> php dom-01.php
root=tribe
lastName=dupont
gender=M
course=dess IAIE
xx exists=false
person: jean dupont (M)
person: charline martin (F)
<teacher>
        <person gender="M">
            <lastName>dupont</lastName>
            <firstName>jean</firstName>
            <age>28</age>
            this is a comment
        </person>
        <section>26</section>
    </teacher>
  • linha 16: a modificação feita pelo script.

Esses dois exemplos não mostram todos os recursos do [SimpleXML] e do [DOM], mas são suficientes para escrevermos uma nova versão do exercício de aplicação. A documentação do PHP os descreve em detalhes: SimpleXML e DOM.