children()

Introdução

SimpleXMLElement::children() retorna os elementos filhos diretos de um nó XML como um novo SimpleXMLElement. Faz parte da extensão SimpleXML do PHP, a forma leve e orientada a objetos de ler e percorrer XML. Você utiliza children() sempre que precisar iterar ou contar os elementos diretamente aninhados dentro de um nó — em vez de acessá-los um nome de propriedade por vez.

Esta página cobre a assinatura e o valor de retorno do método, como iterar sobre filhos, como contá-los, e a parte que a maioria dos tutoriais ignora: ler filhos que estão em um namespace XML.

Sintaxe

public SimpleXMLElement::children(?string $namespace = null, bool $isPrefix = false): ?SimpleXMLElement

Valor de retorno: um SimpleXMLElement que você pode iterar com foreach, indexar como um array ($children[0]) ou passar para count(). Retorna null apenas quando chamado em algo que não é um elemento válido.

children() retorna apenas filhos diretos — não desce para netos. Para alcançar nós mais profundos, chame children() novamente em um filho, ou use XPath.

Iterando sobre filhos

O uso mais comum é percorrer todos os filhos diretos de um nó em loop:

Saída:

PHP Basics - John Doe
Mastering XML - Jane Roe

Aqui $xml é a raiz <books>, e children() retorna cada <book>. Dentro do loop, $book->title e $book->author leem os valores dos netos. Como ambos os elementos <book> compartilham o mesmo nome de tag, o loop é a forma natural de lidar com uma estrutura repetida.

Contando filhos

O objeto retornado funciona com count(), então você pode verificar quantos filhos diretos um nó possui e indexá-los como um array:

<?php
$xml = new SimpleXMLElement('<menu><item>Tea</item><item>Coffee</item><item>Juice</item></menu>');
$children = $xml->children();

echo "Number of items: ", count($children), "\n";
echo "First item: ", $children[0], "\n";

Saída:

Number of items: 3
First item: Tea

Trabalhando com namespaces

É aqui que children() justifica seus parâmetros. Quando um documento usa namespaces XML, uma chamada simples a children() retorna apenas os elementos no namespace padrão — elementos com prefixo são ignorados. Para alcançá-los, passe o namespace.

<?php
$xml = new SimpleXMLElement(
    '<library xmlns:lib="http://example.com/lib">
        <lib:book>Namespaced Book</lib:book>
        <note>Plain note</note>
    </library>'
);

// No namespace: only children in the default namespace
echo count($xml->children()), " default-namespace child(ren)\n";

// Pass the namespace URI to reach the lib: children
$libChildren = $xml->children('http://example.com/lib');
echo count($libChildren), " lib child(ren): ", trim((string) $libChildren->book), "\n";

// Or pass the prefix with $isPrefix = true
$byPrefix = $xml->children('lib', true);
echo count($byPrefix), " child(ren) by prefix\n";

Saída:

1 default-namespace child(ren)
1 lib child(ren): Namespaced Book
1 child(ren) by prefix

Note que o children() simples encontra apenas <note>, enquanto children('http://example.com/lib') encontra o elemento <lib:book>. Se você esquecer disso, os dados com namespace parecem "desaparecer" — um erro clássico do SimpleXML.

Armadilhas comuns

• Somente filhos diretos são retornados. Netos requerem outra chamada a children() ou XPath.
• Filhos com namespace precisam do argumento de namespace. Um children() simples ignora silenciosamente elementos com prefixo.
• Os valores são objetos, não strings. Converta um nó folha para string ((string) $child) ou concatene-o antes de tratá-lo como texto.
• Atributos são separados. children() retorna elementos aninhados; use attributes() para ler os atributos de um elemento.

Conclusão

SimpleXMLElement::children() é a forma padrão de enumerar os elementos filhos diretos de um nó XML em PHP, seja iterando com foreach, contando com count(), ou acessando um namespace específico por meio dos parâmetros $namespace e $isPrefix. Combine-o com attributes() e simplexml_load_string() para analisar XML do mundo real de forma limpa.

Prática