いっしー@Webエンジニア
Webツールプログラミング言語プログラミング学習ITニュースIT用語辞典ポートフォリオ
Webエンジニア向けプログラミング解説動画をYouTubeで配信中！
▶ チャンネル登録はこちら

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

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

作成日: 更新日:

基本的な使い方

querySelectorメソッドは、呼び出し元の要素（Dom\ParentNodeオブジェクト）の子孫要素の中から、指定されたCSSセレクターに一致する最初の要素を見つけて取得するメソッドです。

このメソッドは、ウェブページのHTMLやXMLドキュメントの構造を表現するDOMツリー内で、特定の基準を満たす要素を効率的に探すために使用されます。引数には、検索したい要素を指定するためのCSSセレクター文字列を渡します。例えば、「#header」と指定すればIDが"header"の要素を、「.item」と指定すればクラス名が"item"の要素を、「div p」と指定すればdiv要素の子孫にあるすべてのp要素の中から最初の一つを検索できます。

検索の範囲は、このメソッドを呼び出したParentNodeの内部、つまりそのノード自身とそのすべての子孫要素に限定されます。セレクターに一致する要素が見つかった場合、その要素を表すDom\Elementオブジェクトが返されます。もし複数の要素が一致しても、最も最初に見つかったものだけが返されます。一致する要素が一つも見つからなかった場合は、nullが返されます。

このメソッドは、ウェブスクレイピングや、サーバーサイドで動的にHTMLコンテンツを生成・操作する際など、PHPでDOMを扱う多くの場面で中心的な役割を果たします。JavaScriptのdocument.querySelectorに相当する機能として、初心者の方でも直感的に特定の要素にアクセスし、その内容を変更したり属性を操作したりするために非常に役立つでしょう。

構文(syntax)

1public Dom\Element|null querySelector(string $selectors)

引数(parameters)

string $selectors

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

戻り値(return)

?Dom\Element

指定されたCSSセレクタに一致する最初の要素を返します。一致する要素がない場合はnullを返します。

サンプルコード

PHP DOM querySelectorで要素を取得する

1<?php
2
3// Function to demonstrate the Dom\ParentNode::querySelector method
4function demonstrateQuerySelector(): void
5{
6    // Create a new DOM Document instance
7    $document = new Dom\Document();
8
9    // Load an HTML string into the document
10    // This HTML contains several elements to demonstrate selector usage.
11    $html = <<<HTML
12<!DOCTYPE html>
13<html>
14<head>
15    <title>PHP DOM Query Selector Example</title>
16</head>
17<body>
18    <div id="main-container" class="container">
19        <h1>Introduction</h1>
20        <p class="description">This is a paragraph inside the main container.</p>
21        <div class="item">First Item</div>
22        <div class="item active">Second Item (active)</div>
23        <div class="item">Third Item</div>
24    </div>
25    <div class="container">
26        <p>Another container with more content.</p>
27    </div>
28</body>
29</html>
30HTML;
31
32    // Load the HTML string into the DOM Document
33    // The loadHTML method parses the HTML and builds the DOM tree.
34    $document->loadHTML($html);
35
36    echo "--- Demonstrating Dom\\ParentNode::querySelector ---\n\n";
37
38    // Example 1: Select an element by its ID
39    // querySelector returns the first Dom\Element that matches the specified CSS selector,
40    // or null if no element matches.
41    $mainContainer = $document->querySelector('#main-container');
42    if ($mainContainer !== null) {
43        echo "1. Found element by ID '#main-container': " . $mainContainer->nodeName . "\n";
44        echo "   Text content: " . substr($mainContainer->textContent, 0, 50) . "...\n\n";
45    } else {
46        echo "1. Element with ID '#main-container' not found.\n\n";
47    }
48
49    // Example 2: Select the first element with a specific class
50    // Even if multiple elements have the class 'item', querySelector only returns the very first one it finds.
51    $firstItem = $document->querySelector('.item');
52    if ($firstItem !== null) {
53        echo "2. Found first element with class '.item': " . $firstItem->textContent . "\n\n";
54        // To select ALL elements matching a selector, Dom\ParentNode::querySelectorAll would be used,
55        // which returns a Dom\NodeList (a collection of elements).
56    } else {
57        echo "2. No element with class '.item' found.\n\n";
58    }
59
60    // Example 3: Select an element by combining tag name and class
61    $activeItem = $document->querySelector('div.item.active');
62    if ($activeItem !== null) {
63        echo "3. Found element by 'div.item.active': " . $activeItem->textContent . "\n\n";
64    } else {
65        echo "3. Element 'div.item.active' not found.\n\n";
66    }
67
68    // Example 4: Select a child element using a descendant selector
69    $descriptionParagraph = $document->querySelector('#main-container .description');
70    if ($descriptionParagraph !== null) {
71        echo "4. Found descendant element '#main-container .description': " . $descriptionParagraph->textContent . "\n\n";
72    } else {
73        echo "4. Descendant element '#main-container .description' not found.\n\n";
74    }
75
76    // Example 5: Attempt to find a non-existent element
77    $nonExistent = $document->querySelector('.non-existent-class');
78    if ($nonExistent === null) {
79        echo "5. Attempted to find '.non-existent-class': Element not found (as expected).\n\n";
80    }
81}
82
83// Execute the demonstration function
84demonstrateQuerySelector();
85
86?>

PHP 8のDom\ParentNode::querySelectorメソッドは、HTMLやXMLドキュメントの中から特定の要素を効率的に見つけ出すための機能です。このメソッドは、Dom\Documentクラスのインスタンスや、すでに取得した他のDOM要素（親ノード）から呼び出すことができます。

利用する際は、引数としてCSSセレクターの文字列（例: IDを示す#id名、クラスを示す.クラス名、タグ名、それらの組み合わせなど）を一つ指定します。すると、ドキュメント内でそのセレクターに合致する最初の要素をDom\Elementオブジェクトとして返します。もし該当する要素が一つも見つからない場合は、nullを返しますので、結果がnullでないかを確認してから利用することが重要です。

例えば、サンプルコードではDom\DocumentインスタンスにHTML文字列を読み込んだ後、querySelectorを使用して様々な方法で要素を検索しています。#main-containerで特定のIDを持つ要素を、.itemで最初のクラス名がitemの要素を、div.item.activeでdivタグかつitemとactiveの両方のクラスを持つ要素を探しています。このように、Web開発でおなじみのCSSセレクターを使って柔軟に要素を選択できるため、HTML構造から必要な情報を抽出する際に非常に役立ちます。複数の要素をまとめて取得したい場合には、Dom\ParentNode::querySelectorAllメソッドを利用します。

querySelectorメソッドは、指定したCSSセレクタに合致する「最初の要素」のみを返します。複数の要素があっても、必ず一つしか返さない点に特に注意してください。要素が見つからなかった場合はnullが返されるため、返り値がnullでないか必ずチェックし、安全に処理を進めることが重要です。検索にはIDなら#、クラスなら.といった、一般的なCSSセレクタの記法を利用します。もし、条件に合致する「全ての要素」を取得したい場合は、querySelectorではなくquerySelectorAllメソッドを使用する必要があります。querySelectorAllは要素のリストを返します。このメソッドはHTMLドキュメント全体だけでなく、特定の親要素の中から子要素を探す際にも利用できます。

PHP DOMでquerySelectorを使う

1<?php
2
3/**
4 * Dom\ParentNode::querySelector の使い方と、querySelectorAll の代替手段を示すサンプルコード。
5 *
6 * システムエンジニアを目指す初心者向けに、PHPのDOM拡張でHTML要素を
7 * CSSセレクタを使って選択する方法を簡潔に示します。
8 * また、JavaScriptの querySelectorAll() に相当する機能の実現方法も紹介します。
9 */
10function demonstrateDomSelectors(): void
11{
12    // DOMDocument オブジェクトを新規作成
13    $dom = new DOMDocument();
14
15    // サンプルHTMLコンテンツをロード
16    // ヒアドキュメント構文 (<<<HTML ... HTML;) を使用
17    $html = <<<HTML
18<!DOCTYPE html>
19<html>
20<head>
21    <title>PHP DOM Selector Example</title>
22</head>
23<body>
24    <div id="container">
25        <h1 class="heading">PHP DOMセレクタの基本</h1>
26        <p class="text-item">これは最初の段落です。</p>
27        <p class="text-item">これは2番目の段落です。</p>
28        <a href="https://example.com/link1" class="link-item">リンク1</a>
29        <a href="https://example.com/link2" class="link-item">リンク2</a>
30    </div>
31    <p class="text-item">これはコンテナ外の3番目の段落です。</p>
32</body>
33</html>
34HTML;
35    // HTMLをDOMにロード。loadHTMLが生成する可能性のある警告を抑制 (@)
36    @$dom->loadHTML($html);
37
38    // DOMDocument の documentElement は <html> 要素を指し、
39    // Dom\ParentNode インターフェースを実装しているため、querySelector を呼び出せます。
40    $rootElement = $dom->documentElement;
41
42    if ($rootElement instanceof Dom\ParentNode) {
43        echo "--- Dom\\ParentNode::querySelector の使用例 (単一要素の選択) ---" . PHP_EOL;
44
45        // 1. IDセレクタで要素を選択: IDが "container" の要素
46        // querySelector はマッチする最初の要素のみを返します。
47        $container = $rootElement->querySelector('#container');
48        if ($container) {
49            echo "1. ID 'container' の要素が見つかりました: <" . $container->nodeName . ">" . PHP_EOL;
50
51            // 2. クラスセレクタと要素名で要素を選択: "container" 内の最初の "p" 要素でクラスが "text-item" のもの
52            $firstParagraphInContainer = $container->querySelector('p.text-item');
53            if ($firstParagraphInContainer) {
54                echo "2. 'container' 内の最初の '.text-item' 段落: " . $firstParagraphInContainer->textContent . PHP_EOL;
55            } else {
56                echo "2. 'container' 内に '.text-item' 段落は見つかりませんでした。" . PHP_EOL;
57            }
58
59            // 3. 別のセレクタで要素を選択: "container" 内の最初の "a" 要素でクラスが "link-item" のもの
60            $firstLinkInContainer = $container->querySelector('a.link-item');
61            if ($firstLinkInContainer) {
62                echo "3. 'container' 内の最初の '.link-item' リンク: " . $firstLinkInContainer->textContent . PHP_EOL;
63            } else {
64                echo "3. 'container' 内に '.link-item' リンクは見つかりませんでした。" . PHP_EOL;
65            }
66        } else {
67            echo "1. ID 'container' の要素は見つかりませんでした。" . PHP_EOL;
68        }
69
70        echo PHP_EOL;
71        echo "--- querySelectorAll (複数の要素選択) の代替手段 (DOMXPath の使用) ---" . PHP_EOL;
72        // PHPのDOM拡張には、JavaScriptの document.querySelectorAll() に直接対応するメソッドはありません。
73        // 複数の要素をCSSセレクタに似た方法で選択するには、DOMXPath クラスを使用するのが一般的です。
74
75        // DOMXPath オブジェクトを作成し、DOMDocument を関連付けます。
76        $xpath = new DOMXPath($dom);
77
78        // 4. すべてのクラスが "text-item" の "p" 要素を選択 (CSS: p.text-item に相当)
79        // XPathクエリ: "//p[@class='text-item']" は、ドキュメント全体のどこかにある、
80        // クラス属性が 'text-item' であるすべての p 要素を選択します。
81        $allTextItems = $xpath->query("//p[@class='text-item']");
82
83        echo "4. すべての '.text-item' 段落:" . PHP_EOL;
84        if ($allTextItems->count() > 0) {
85            foreach ($allTextItems as $item) {
86                echo "   - " . $item->textContent . PHP_EOL;
87            }
88        } else {
89            echo "   見つかりませんでした。" . PHP_EOL;
90        }
91
92        // 5. すべてのクラスが "link-item" の "a" 要素を選択 (CSS: a.link-item に相当)
93        // XPathクエリ: "//a[@class='link-item']" は、ドキュメント全体のどこかにある、
94        // クラス属性が 'link-item' であるすべての a 要素を選択します。
95        $allLinkItems = $xpath->query("//a[@class='link-item']");
96
97        echo "5. すべての '.link-item' リンク:" . PHP_EOL;
98        if ($allLinkItems->count() > 0) {
99            foreach ($allLinkItems as $link) {
100                echo "   - " . $link->textContent . " (URL: " . $link->getAttribute('href') . ")" . PHP_EOL;
101            }
102        } else {
103            echo "   見つかりませんでした。" . PHP_EOL;
104        }
105
106    } else {
107        echo "エラー: documentElement は Dom\\ParentNode ではありませんでした。" . PHP_EOL;
108    }
109}
110
111// 関数を実行してデモンストレーションを開始
112demonstrateDomSelectors();

PHPのDOM拡張では、ウェブページ（HTML）の要素をプログラムから操作するために、CSSセレクタを利用して特定の要素を見つけることができます。Dom\ParentNode::querySelectorメソッドは、指定されたCSSセレクタに合致する要素を、文書の中から最初に見つかったものだけ選択して返します。このメソッドは引数としてstring $selectorsを受け取り、CSSセレクタ（例えばIDセレクタの#id名、クラスセレクタの.class名、要素とクラスの組み合わせであるdiv.class名など）を指定します。戻り値は、選択された要素をDom\Elementオブジェクトとして返しますが、セレクタに合致する要素が見つからない場合はnullを返します。これにより、特定のIDを持つ要素や、特定のクラスを持つ最初の要素などを簡潔なコードで見つけ出すことが可能です。

一方で、JavaScriptのdocument.querySelectorAll()のように、指定したセレクタに合致するすべての要素を一括で選択する直接的なPHPメソッドは、DOM拡張には標準で提供されていません。複数の要素を選択したい場合には、DOMXPathクラスを利用するのが一般的な代替手段となります。DOMXPathを使用することで、XPathという別の強力なクエリ言語を使って、より柔軟かつ高度な条件で文書中の複数の要素を検索し、それらをまとめて取得することができます。この方法を用いることで、例えば特定のクラスを持つすべての段落要素や、特定の属性を持つすべてのリンク要素などを効率的に取得し、それぞれに対して必要な処理を行うことが可能になります。

Dom\ParentNode::querySelectorは、指定されたCSSセレクタにマッチする最初の要素のみを返します。要素が見つからない場合はnullが返されるため、必ず返り値がnullでないかをチェックしてから操作を行ってください。PHPにはJavaScriptのquerySelectorAllのような複数の要素を一度に取得する直接のメソッドはありません。複数の要素を選択したい場合は、DOMXPathクラスを利用するのが一般的です。DOMXPathはCSSセレクタとは異なるXPathという記法を使用しますので、基本的なクエリの書き方を学ぶと効率的に要素を抽出できます。サンプルコードでloadHTML関数の前に記述している@記号は、PHPが生成する警告を抑制するものですが、開発中は警告を確認し、本番環境では適切なエラーハンドリングを導入することをおすすめします。

関連コンテンツ

関連IT用語