Avalia a expressão XPath fornecida

# DOMXPath::query

(PHP 5, PHP 7, PHP 8)

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

### Descrição

public function 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

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open