【PHP8.x】Dom\HTMLElement::querySelectorAll()メソッドの使い方

querySelectorAllメソッドの使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2025年11月23日

基本的な使い方

querySelectorAllメソッドは、Dom\HTMLElementクラスのインスタンスから呼び出され、指定されたCSSセレクタに一致する全ての子孫要素を検索し、それらをDOMNodeListオブジェクトとして返すメソッドです。このメソッドは、HTML文書内で特定の条件を満たす複数の要素を効率的に見つけ出す際に非常に有用です。

引数には、検索したい要素を指定するためのCSSセレクタ文字列を渡します。例えば、「.my-class」を指定すればmy-classというクラスを持つ要素を、「div > p」を指定すればdiv要素の直下にあるp要素を検索できます。検索の対象となるのは、このメソッドを呼び出した要素の子孫要素のみであり、呼び出し元要素自身は含まれません。

一致する要素が見つかった場合、それらの要素はDOMNodeListオブジェクトとして返されます。このDOMNodeListは、取得時点の要素の状態を保持する静的なリストであり、その後にDOMの構造が変更されても、このリストの内容が動的に変化することはありません。もし一致する要素が一つも見つからなかった場合は、空のDOMNodeListが返されます。この機能により、PHPでWebページの内容を解析・操作する際に、特定の要素群をまとめて取得し、一括で処理することが可能となります。

構文(syntax)


1<?php
2$domNodeListObject = $domHTMLElementObject->querySelectorAll('css_selector_string');
3?>

引数(parameters)

string $selectors

string $selectors: 検索したいCSSセレクタを指定する文字列

戻り値(return)

Dom\NodeList

指定されたCSSセレクタに一致するすべての要素のリストをDom\NodeListオブジェクトとして返します。

サンプルコード

PHP DOM querySelectorAll で要素を検索する


1<?php
2
3/**
4 * 指定されたHTML文字列からDOM要素を解析し、CSSセレクタに一致する要素を検索して表示します。
5 * Dom\HTMLElement::querySelectorAll の基本的な使い方をシステムエンジニア初心者向けに示します。
6 *
7 * @param string $html HTML文字列。
8 * @param string $selector 検索に使用するCSSセレクタ文字列 (例: 'div', '.class-name', '#id-name')。
9 * @return void
10 */
11function findAndDisplayElements(string $html, string $selector): void
12{
13    // HTML文字列をDom\HTMLDocumentオブジェクトに読み込みます。
14    // PHP 8以降の新しいDOM拡張では、HTMLドキュメントの解析にDom\HTMLDocumentクラスが利用できます。
15    $document = new Dom\HTMLDocument();
16    $document->loadHTML($html);
17
18    // ドキュメントのルート要素（通常は <html>）を取得します。
19    // Dom\HTMLElement クラスは querySelectorAll メソッドを持っており、
20    // これを使って子孫要素からセレクタに一致する要素を検索します。
21    /** @var Dom\HTMLElement|null $rootElement */
22    $rootElement = $document->documentElement;
23
24    if (!$rootElement) {
25        echo "エラー: ドキュメントのルート要素が見つかりませんでした。\n";
26        return;
27    }
28
29    echo "--- セレクタ '{$selector}' の検索結果 ---\n";
30
31    // querySelectorAll メソッドを呼び出し、指定されたCSSセレクタに一致するすべての要素を取得します。
32    // 戻り値は Dom\NodeList で、一致する要素のコレクションです。
33    $nodeList = $rootElement->querySelectorAll($selector);
34
35    if ($nodeList->count() === 0) {
36        echo "一致する要素は見つかりませんでした。\n";
37        return;
38    }
39
40    // 取得した Dom\NodeList をループし、各要素の情報を表示します。
41    foreach ($nodeList as $index => $node) {
42        // Dom\NodeList に含まれる要素は Dom\HTMLElement 型であることが期待されます。
43        if ($node instanceof Dom\HTMLElement) {
44            echo "要素 " . ($index + 1) . ":\n";
45            echo "  タグ名: " . $node->tagName . "\n";
46            // 要素のテキストコンテンツを表示します。trim() で余分な空白を除去しています。
47            echo "  テキストコンテンツ: " . trim($node->textContent) . "\n";
48            echo "  --------------------\n";
49        }
50    }
51}
52
53// サンプルとして使用するHTML文字列を定義します。
54$sampleHtml = <<<HTML
55<!DOCTYPE html>
56<html>
57<head>
58    <title>PHP DOM QuerySelectorAll デモ</title>
59</head>
60<body>
61    <header>
62        <h1>商品情報</h1>
63    </header>
64    <main>
65        <div id="product-container">
66            <div class="product-item">
67                <h2>商品A</h2>
68                <p class="description">詳細情報1。</p>
69            </div>
70            <div class="product-item featured">
71                <h2>商品B (おすすめ)</h2>
72                <p class="description">詳細情報2。</p>
73            </div>
74        </div>
75        <div class="advertisement">
76            <p class="description">広告情報。</p>
77        </div>
78    </main>
79</body>
80</html>
81HTML;
82
83// '.product-item' クラスを持つすべての要素を検索し、その情報を表示します。
84findAndDisplayElements($sampleHtml, '.product-item');
85

PHP 8のDom\HTMLElement::querySelectorAllメソッドは、HTMLドキュメント内でCSSセレクタに一致する要素を効率的に検索し、取得する際に利用されます。このサンプルコードは、指定されたHTML文字列を解析し、特定のCSSセレクタに合致するすべてのHTML要素を見つけて表示する基本的な流れを示しています。

まず、入力されたHTML文字列はDom\HTMLDocumentオブジェクトに読み込まれ、そのDOMツリーが構築されます。その後、ドキュメントのルート要素であるDom\HTMLElementを取得し、そのquerySelectorAllメソッドを呼び出します。このメソッドには、検索したい要素を指定するCSSセレクタ文字列（例えば、クラス名を表す.product-itemやタグ名を表すdivなど）を引数として渡します。

querySelectorAllは、セレクタに一致するすべての要素をDom\NodeListというコレクション形式で返します。この戻り値は、一致した要素が一つもない場合は空のリストとなり、複数の要素が見つかった場合はそれらすべてが含まれます。コードでは、このDom\NodeListをループ処理し、各要素がDom\HTMLElementであることを確認しながら、そのタグ名やテキストコンテンツといった情報を出力しています。これにより、HTMLコンテンツから必要な情報をプログラム的に抽出し、活用する方法を学ぶことができます。

このサンプルコードはPHP 8以降で導入された新しいDOM拡張を使用しており、従来のDOMDocumentとは使い方が異なりますのでご注意ください。querySelectorAllメソッドはCSSセレクタを引数にとるため、セレクタの正しい記述方法を理解することが重要です。検索結果として要素が見つからなかった場合でもエラーにはならず、空のDom\NodeListが返されます。そのため、count()メソッドで要素の有無を必ず確認し、適切な処理を行う必要があります。また、解析するHTML文字列が不正な形式だと、DOMツリーが正しく構築されず、意図した結果が得られない可能性があります。取得した要素はDom\HTMLElementとして扱えます。