DOMXPath::query

(PHP 5, PHP 7, PHP 8)

DOMXPath::query — Évalue l'expression XPath donnée

Description

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

Évalue l'expression expression XPath donnée.

Liste de paramètres

expression: L'expression XPath à exécuter.
contextNode: Le paramètre optionnel contextNode peut être spécifié pour effectuer des requêtes XPath relatives. Par défaut, les requêtes sont relatives à l'élément racine.
registerNodeNS: Indique s'il faut automatiquement enregistrer les préfixes de namespace en vigueur du nœud de contexte dans l'objet DOMXPath. Cela peut être utilisé pour éviter d'avoir à appeler manuellement DOMXPath::registerNamespace() pour chaque namespace en vigueur. En cas de conflit de préfixes de namespace, seul le préfixe de namespace descendant le plus proche est enregistré.

Valeurs de retour

Retourne un DOMNodeList contenant tous les nœuds correspondant à l'expression expression XPath donnée. Toutes les expressions qui ne retournent pas de nœud retournent un DOMNodeList vide.

Si le paramètre expression est malformé ou le paramètre contextNode est invalide, DOMXPath::query() retourne false.

Erreurs / Exceptions

Les erreurs suivantes peuvent survenir lors de l'utilisation d'une expression qui invoque des callbacks PHP.

Lance une Error si un callback PHP est invoqué mais qu'aucun callback n'est enregistré, ou si le callback nommé n'est pas enregistré.
Lance une TypeError si la syntaxe php:function est utilisée et que le nom du gestionnaire n'est pas une chaîne de caractères.
Lance une Error si un objet non DOM est retourné par un callback.

Exemples

Exemple #1 Récupération de tous les livres anglais

<?php

$doc = new DOMDocument;

// Nous ne voulons pas nous soucier des espaces blancs
$doc->preserveWhiteSpace = false;

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

$xpath = new DOMXPath($doc);

// Nous commençons à l'élément racine
$query = '//book/chapter/para/informaltable/tgroup/tbody/row/entry[. = "en"]';

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

foreach ($entries as $entry) {
    echo "Livre trouvé {$entry->previousSibling->previousSibling->nodeValue}," .
         " par {$entry->previousSibling->nodeValue}\n";
}
?>

L'exemple ci-dessus va afficher :

Livre trouvé : The Grapes of Wrath, par John Steinbeck
Livre trouvé : The Pearl, par John Steinbeck

Nous pouvons également utiliser le paramètre contextNode pour raccourcir notre expression :

<?php

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

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

$xpath = new DOMXPath($doc);

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

// notre requête est relative au nœud tbody
$query = 'row/entry[. = "en"]';

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

foreach ($entries as $entry) {
    echo "Livre trouvé : {$entry->previousSibling->previousSibling->nodeValue}," .
         " par {$entry->previousSibling->nodeValue}\n";
}
?>

Voir aussi

DOMXPath::evaluate() - Évalue une expression XPath donnée et retourne un résultat typé si possible