【PHP8.x】querySelectorAllメソッドの使い方

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

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

基本的な使い方

querySelectorAllメソッドは、PHPのDom\HTMLDocumentクラスに属し、HTMLドキュメント内で指定されたCSSセレクターに一致する全ての要素を取得するために使用されるメソッドです。このメソッドは、Webページの内容を解析したり、特定のHTML要素をプログラムから操作したりする際に非常に強力なツールとなります。

具体的には、引数としてCSSセレクターの文字列を受け取ります。例えば、'div.item'を指定すれば、class="item"を持つ全ての<div>要素を検索しますし、'#main-content p'を指定すれば、id="main-content"を持つ要素内の全ての<p>要素を検索するといった形で、柔軟な要素の指定が可能です。

検索の結果、一致する要素が見つかった場合、それらの要素をDom\NodeListオブジェクトとして返します。このDom\NodeListは、取得した要素を順次処理するためのコレクションとして機能します。もし指定したCSSセレクターに一致する要素が一つもなかった場合でも、エラーになることなく空のDom\NodeListオブジェクトが返されます。

このメソッドは、HTMLドキュメントの構造を理解し、その中から特定の情報を効率的に抽出するデータ解析やWebスクレイピングなどの用途において、システムエンジニアが頻繁に利用する基本的な機能の一つです。

構文(syntax)


1<?php
2
3// Dom\HTMLDocument クラスのインスタンス $document が存在し、
4// HTMLドキュメントがロード済みであることを前提とします。
5
6$selector = 'div.main > p.item'; // 検索対象となるCSSセレクタ文字列
7$nodeList = $document->querySelectorAll($selector); // querySelectorAll メソッドの呼び出し
8
9?>

引数(parameters)

string $selectors

string $selectors: 検索対象となるCSSセレクター文字列

戻り値(return)

Dom\NodeList

指定されたCSSセレクターに一致するすべてのDOMノードのリストを返します。

サンプルコード

PHP DomDocument::querySelectorAllで要素を検索する


1<?php
2
3/**
4 * 指定されたHTMLコンテンツからCSSセレクタに一致する要素を検索し、その情報を表示します。
5 *
6 * @param string $htmlContent 検索対象のHTML文字列。
7 * @param string $selector    要素を選択するためのCSSセレクタ（例: 'p', '.class', '#id', 'div > a'）。
8 * @return void
9 */
10function findAndDisplaySelectedElements(string $htmlContent, string $selector): void
11{
12    // Dom\HTMLDocument の新しいインスタンスを作成します。
13    // PHP 8 からは DOM 操作にこのクラスの使用が推奨されています。
14    $document = new Dom\HTMLDocument();
15
16    // 提供されたHTMLコンテンツをDOMドキュメントにロードします。
17    // loadHTML はHTMLのパースエラーで警告を出すことがあるため、
18    // 一時的に警告を抑制するために '@' を使用する場合があります。
19    // 実際のアプリケーションでは、エラーハンドリングを適切に行うことを検討してください。
20    @$document->loadHTML($htmlContent);
21
22    // querySelectorAll メソッドを使用して、指定されたCSSセレクタに一致するすべての要素を選択します。
23    // このメソッドは、一致する要素のコレクションである Dom\NodeList オブジェクトを返します。
24    $elements = $document->querySelectorAll($selector);
25
26    echo "--- セレクタ '{$selector}' に一致する要素 ---\n";
27
28    // Dom\NodeList が空かどうかを確認します。
29    if ($elements->count() === 0) {
30        echo "一致する要素は見つかりませんでした。\n";
31        echo "----------------------------------------\n";
32        return;
33    }
34
35    // 選択された各要素（Dom\Element）をループ処理します。
36    // Dom\NodeList はイテラブルであり、各要素は Dom\Node のサブタイプです。
37    // 通常、CSSセレクタで選択される要素は Dom\Element 型になります。
38    foreach ($elements as $index => $element) {
39        // Dom\Element であることを確認し、そのプロパティを表示します。
40        // Dom\Element は tagName や textContent などのプロパティを持ちます。
41        if ($element instanceof Dom\Element) {
42            echo "要素 #" . ($index + 1) . ":\n";
43            echo "  タグ名: " . $element->tagName . "\n";
44            echo "  テキストコンテンツ: " . trim($element->textContent) . "\n";
45            // 例: 特定の属性が存在すれば表示します。
46            if ($element->hasAttribute('class')) {
47                echo "  クラス属性: " . $element->getAttribute('class') . "\n";
48            }
49            echo "\n";
50        }
51    }
52    echo "----------------------------------------\n";
53}
54
55// サンプルHTMLコンテンツを定義します。
56$sampleHtml = <<<HTML
57<!DOCTYPE html>
58<html>
59<head>
60    <title>PHP Dom\HTMLDocument::querySelectorAll Example</title>
61</head>
62<body>
63    <h1>DOM操作のサンプル</h1>
64    <div id="container">
65        <p class="message">最初のメッセージです。</p>
66        <p>これは通常の段落です。</p>
67        <ul>
68            <li><a href="/page1">ページ1</a></li>
69            <li><a href="/page2" class="message">ページ2</a></li>
70        </ul>
71    </div>
72    <p class="message">フッターのメッセージです。</p>
73</body>
74</html>
75HTML;
76
77// 実行例: クラス名 'message' を持つすべての要素を選択し、表示します。
78findAndDisplaySelectedElements($sampleHtml, '.message');

Dom\HTMLDocument::querySelectorAll メソッドは、PHP 8で推奨される Dom\HTMLDocument クラスに属し、HTMLコンテンツから特定の要素を効率的に検索するために使用されます。

引数として string $selectors を受け取ります。これはCSSセレクタの文字列であり、ウェブページで特定の要素を指定する際に使われる「目印」のようなものです。例えば、すべての段落要素を指定する 'p' や、特定のクラス名を持つ要素を指定する '.className'、あるいはIDを持つ要素を指定する '#idName' などがあります。この引数によって、どのような要素を探したいのかをメソッドに伝えます。

戻り値は Dom\NodeList 型です。これは、指定されたCSSセレクタに一致するすべての要素の集まり（リスト）を表します。一致する要素が一つもなかった場合は空のリストが返され、一致する要素があれば、その一つ一つにアクセスして情報を取得できます。サンプルコードでは、まずHTMLコンテンツを Dom\HTMLDocument に読み込み、querySelectorAll でクラス名 'message' を持つすべての要素を選択しています。その後、返された要素のリストを foreach ループで一つずつ処理し、そのタグ名やテキストコンテンツを表示しています。これにより、ウェブページのようなHTML構造から必要な情報を取り出すことが可能になります。

このコードはPHP 8で推奨されるDom\HTMLDocumentクラスを使い、querySelectorAllでCSSセレクタに一致するHTML要素を検索します。loadHTMLメソッドはHTMLパース時に警告を出すことがあるため、サンプルでは@で抑制していますが、本番環境ではエラーハンドリングを適切に実装することが非常に重要です。

querySelectorAllは一致する要素をDom\NodeListとして返します。要素がない場合も空のリストを返すため、処理前にcount()で確認すると良いでしょう。ループで要素を処理する際は、それがDom\Elementであることを確認し、tagNameやtextContentで情報を安全に取得してください。特にtextContentには不要な空白が含まれる場合があるため、trim()で整形することをお勧めします。