DOMXPath::query

(PHP 5, PHP 7, PHP 8)

DOMXPath::query — Avalia a expressão XPath fornecida

Descrição

public DOMXPath::query(string $expression, ?DOMNode $contextNode = null, bool $registerNodeNS = true): mixed

Executa a expression XPath fornecida.

Parâmetros

expression: A expressão XPath a ser executada.
contextNode: O contextNode opcional pode ser especificado para realizar consultas XPath relativas. Por padrão, as consultas são relativas ao elemento raiz.
registerNodeNS: Define se deve-se registrar automaticamente os prefixos de espaços de nomes dentro do escopo no nó de contexto para o objeto DOMXPath. Isto pode ser usado para evitar a necessidade de se chamar DOMXPath::registerNamespace() manuallmente para cada espaço de nome dentro do escopo. Quando existir um conflito entre prefixos de espaços de nomes, apenas o prefixo do espaço de nome descendente mais próximo será registrado.

Valor Retornado

Retorna uma DOMNodeList contendo todos os nós que correspondem à expression XPath fornecida. Qualquer expressão que não retorne nós resultará em uma DOMNodeList vazia.

Se a expression estiver malformada ou o contextNode for inválido, DOMXPath::query() retorna false.

Erros/Exceções

Os seguintes erros são possíveis ao usar uma expressão que invoca retornos de chamada PHP.

Lança um Error se um retorno de chamada do PHP for invocado, mas não houver nenhum retorno de chamada registrado ou se o retorno de chamada nomeado não tiver sido registrado.
Lança um TypeError se a sintaxe php:function for usada e o nome do manipulador não for uma string.
Lança um Error se um objeto não DOM foi retornado de um retorno de chamada.

Exemplos

Exemplo #1 Obtendo todos os livros em inglês

<?php

$doc = new DOMDocument;

// Não queremos nos preocupar com espaços em branco
$doc->preserveWhiteSpace = false;

$doc->load('examples/book-docbook.xml');

$xpath = new DOMXPath($doc);

// Começamos do elemento raiz
$query = '//book/chapter/para/informaltable/tgroup/tbody/row/entry[. = "en"]';

$entries = $xpath->query($query);

foreach ($entries as $entry) {
    echo "Encontrado {$entry->previousSibling->previousSibling->nodeValue}," .
         " por {$entry->previousSibling->nodeValue}\n";
}
?>

O exemplo acima produzirá:

Encontrado The Grapes of Wrath, por John Steinbeck
Encontrado The Pearl, por John Steinbeck

Também podemos usar o parâmetro contextNode para encurtar nossa expressão:

<?php

$doc = new DOMDocument;
$doc->preserveWhiteSpace = false;

$doc->load('examples/book-docbook.xml');

$xpath = new DOMXPath($doc);

$tbody = $doc->getElementsByTagName('tbody')->item(0);

// nossa consulta é relativa ao nó tbody
$query = 'row/entry[. = "en"]';

$entries = $xpath->query($query, $tbody);

foreach ($entries as $entry) {
    echo "Encontrado {$entry->previousSibling->previousSibling->nodeValue}," .
         " por {$entry->previousSibling->nodeValue}\n";
}
?>

Veja Também

DOMXPath::evaluate() - Avalia a expressão XPath fornecida e retorna um resultado tipado se possível