【PHP8.x】DOMDocumentType::compareDocumentPosition()メソッドの使い方

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

作成日: 2025年09月11日更新日: 2025年12月02日

基本的な使い方

compareDocumentPositionメソッドは、DOMDocumentTypeクラスに属するメソッドであり、あるノードと別のノードのドキュメント内での位置関係を比較するために使用されます。具体的には、2つのノードがドキュメント内でどの程度関連しているかをビットマスクとして表現した整数値を返します。この値を見ることで、一方のノードが他方のノードの前にあるか、後にあるか、あるいはそれらのノードが同じドキュメントに属しているかどうかなどを判断できます。

このメソッドは、2つのノード間の関係性をプログラムで判断する必要がある場合に非常に役立ちます。例えば、XMLやHTMLドキュメントの構造を解析し、特定の要素の親子関係や兄弟関係を特定する場合などに利用できます。

返される値は、以下の定数の組み合わせ（ビット演算）で構成されます。

DOCUMENT_POSITION_DISCONNECTED: 2つのノードが異なるドキュメントに属しているか、どちらか一方または両方がドキュメントに属していません。
DOCUMENT_POSITION_PRECEDING: 比較対象のノードが指定されたノードよりも前に出現します。
DOCUMENT_POSITION_FOLLOWING: 比較対象のノードが指定されたノードよりも後に表示されます。
DOCUMENT_POSITION_CONTAINS: 指定されたノードが比較対象のノードを含んでいます。
DOCUMENT_POSITION_CONTAINED_BY: 比較対象のノードが指定されたノードに含まれています。
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: 実装に依存する比較結果です。

これらの定数を適切に解析することで、2つのノード間の正確な関係性を把握し、それに基づいて必要な処理を行うことができます。システムエンジニアとしては、DOMDocumentTypeオブジェクトを操作する際に、このメソッドを活用してドキュメント構造を効率的に解析することが可能です。

構文(syntax)


1DOMDocumentType::compareDocumentPosition( DOMNode $other ): int

引数(parameters)

DOMNode $other

DOMNode $other: 比較対象となる別の DOMNode オブジェクト

戻り値(return)

int

このメソッドは、2つのDOMDocumentTypeノードの相対的な位置を示す整数値を返します。返される値は、ビットマスクとして解釈され、ノード間の関係性（先行、後続、同一、親など）を示します。

サンプルコード

PHP DOM: compareDocumentPositionでノード位置比較


1<?php
2
3declare(strict_types=1);
4
5/**
6 * このファイルは、PHPのDOM拡張機能における
7 * DOMDocumentType::compareDocumentPosition メソッドの使用例を示します。
8 *
9 * DOMDocumentType はドキュメントのDOCTYPE宣言を表し、
10 * compareDocumentPosition は2つのノード間の相対的な位置関係を比較します。
11 *
12 * システムエンジニアを目指す初心者でも理解しやすいように、DOMツリーの基本と
13 * ノード比較の概念をシンプルなHTMLと出力で解説します。
14 *
15 * このコードは、PHPの推奨コーディングスタイル（PSR）に従い、
16 * phpDocumentorのドキュメント生成ツールで解析可能なPHPDocコメントを含みます。
17 * Composerは直接使用しませんが、これはPHP標準のDOM拡張機能であるため、
18 * 一般的なPHPプロジェクトでのComposer利用を意識したコード構造を維持しています。
19 */
20
21/**
22 * 2つのDOMノード間の位置関係を比較し、結果を分かりやすく出力するヘルパー関数。
23 *
24 * compareDocumentPositionメソッドは、ノード間の位置関係を示すビットマスクを返します。
25 * この関数は、返されたビットマスクを個々のフラグでチェックし、結果を解釈して出力します。
26 * 各フラグは、DOM_DOCUMENT_POSITION_* 定数として定義されています。
27 *
28 * @param DOMNode $node1 比較の基準となるノード（このノードから$node2への位置を比較）。
29 * @param DOMNode $node2 比較対象のノード。
30 * @param string  $node1Name $node1の表示名（出力メッセージ用）。
31 * @param string  $node2Name $node2の表示名（出力メッセージ用）。
32 * @return void
33 */
34function printComparisonResult(DOMNode $node1, DOMNode $node2, string $node1Name, string $node2Name): void
35{
36    // compareDocumentPosition メソッドを呼び出し、2つのノード間の相対位置を取得
37    $position = $node1->compareDocumentPosition($node2);
38
39    echo sprintf("--- 比較: '%s' (基準) と '%s' (対象) ---\n", $node1Name, $node2Name);
40
41    // 返されたビットマスクを個々のフラグでチェックし、意味を解釈
42    if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
43        echo " - ノードはドキュメントツリーで接続されていません。\n";
44    }
45    if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
46        // $node2 が $node1 の前に現れる
47        echo sprintf(" - '%s' は '%s' の前に現れます。\n", $node2Name, $node1Name);
48    }
49    if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
50        // $node2 が $node1 の後に現れる
51        echo sprintf(" - '%s' は '%s' の後に現れます。\n", $node2Name, $node1Name);
52    }
53    if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
54        // $node1 が $node2 を含んでいる
55        echo sprintf(" - '%s' は '%s' を含んでいます。\n", $node1Name, $node2Name);
56    }
57    if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
58        // $node1 が $node2 に含まれている
59        echo sprintf(" - '%s' は '%s' に含まれています。\n", $node1Name, $node2Name);
60    }
61    if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
62        echo " - 実装固有の比較結果です（特別な状況下でのみ設定されます）。\n";
63    }
64    if ($position === 0) {
65        // どちらのフラグも設定されていない場合、ノードは同じ
66        echo " - ノードは同じです。\n";
67    }
68    echo "\n";
69}
70
71// DOMDocumentのインスタンスを作成します。
72$dom = new DOMDocument();
73
74// ドキュメントツリーを構築するためにHTML文字列をロードします。
75// <!DOCTYPE html> は DOMDocumentType ノードとして解析されます。
76// <html>, <head>, <body> などのタグは DOMElement ノードです。
77$htmlContent = <<<HTML
78<!DOCTYPE html>
79<html>
80<head>
81    <title>サンプルページ</title>
82</head>
83<body>
84    <h1>こんにちは、世界！</h1>
85    <p>これはサンプルの段落です。</p>
86</body>
87</html>
88HTML;
89
90// HTMLをDOMDocumentにロード
91$dom->loadHTML($htmlContent);
92
93// DOMDocumentType ノード（DOCTYPE宣言）を取得します。
94// DOMDocumentTypeはDOMDocumentのdoctypeプロパティからアクセスできます。
95$doctypeNode = $dom->doctype;
96
97if ($doctypeNode === null) {
98    echo "エラー: DOCTYPE ノードが見つかりませんでした。HTMLのロードに問題がある可能性があります。\n";
99    exit(1); // スクリプトを終了
100}
101
102// 比較対象となる他の主要なノードを取得します。
103$htmlElementNode = $dom->documentElement; // <html> ノード (ドキュメントのルート要素)
104$headElementNode = $dom->getElementsByTagName('head')->item(0); // <head> ノード
105$bodyElementNode = $dom->getElementsByTagName('body')->item(0); // <body> ノード
106$h1ElementNode = $dom->getElementsByTagName('h1')->item(0); // <h1> ノード
107
108echo "--- DOMDocumentType::compareDocumentPosition の使用例 ---\n\n";
109
110// DOCTYPE ノードと他の主要なノードとの位置関係を比較します。
111// DOCTYPEは通常、ドキュメントの最初のノードであり、他のノードとは接続されておらず、
112// その後に他のノードが続きます。
113if ($htmlElementNode) {
114    printComparisonResult($doctypeNode, $htmlElementNode, "DOCTYPE", "<html>");
115}
116if ($headElementNode) {
117    printComparisonResult($doctypeNode, $headElementNode, "DOCTYPE", "<head>");
118}
119if ($bodyElementNode) {
120    printComparisonResult($doctypeNode, $bodyElementNode, "DOCTYPE", "<body>");
121}
122if ($h1ElementNode) {
123    printComparisonResult($doctypeNode, $h1ElementNode, "DOCTYPE", "<h1>");
124}
125
126echo "--- 別のノード間の比較例 (参考: 包含関係) ---\n\n";
127
128// 参考として、HTML要素とその子要素の比較も示します。
129// <html> 要素は <h1> 要素を含んでいます。
130if ($htmlElementNode && $h1ElementNode) {
131    // <html> が <h1> を含んでいる関係
132    printComparisonResult($htmlElementNode, $h1ElementNode, "<html>", "<h1>");
133    // <h1> が <html> に含まれている関係
134    printComparisonResult($h1ElementNode, $htmlElementNode, "<h1>", "<html>");
135}
136

PHPのDOMDocumentType::compareDocumentPositionメソッドは、DOMツリー内の2つのノード間の相対的な位置関係を比較するために使用されます。このメソッドは、比較対象となるDOMNode $otherを引数に取り、基準となるノード（この場合はDOMDocumentTypeオブジェクト自身）から見て、$otherノードがどのような位置にあるかを示す整数値を返します。

戻り値の整数値はビットマスクであり、複数のDOM_DOCUMENT_POSITION_*定数を組み合わせて、ノードが接続されているか、前にあるか、後ろにあるか、含まれているか、または含んでいるかといった詳細な情報を表現します。例えば、DOM_DOCUMENT_POSITION_FOLLOWINGは対象ノードが基準ノードの後に続くことを、DOM_DOCUMENT_POSITION_CONTAINSは基準ノードが対象ノードを含んでいることを示します。この機能は、複雑なHTMLやXML構造を解析・操作するシステムにおいて、ノード間の依存関係を正確に判断する際に役立ちます。

提供されたサンプルコードでは、DOMDocumentにHTML文字列をロードし、その<!DOCTYPE html>宣言を表すDOMDocumentTypeノードを基準として、<html>や<h1>といった他の要素ノードとの位置関係を比較しています。これにより、ドキュメントツリーにおけるノードの基本的な配置や関係性を具体的に理解できます。コードにはphpDocumentorで解析可能なPHPDocコメントが含まれており、PHPプロジェクトでの標準的なコーディングプラクティスとドキュメント化の重要性を示しています。ComposerはDOM拡張機能の利用自体には直接関係しませんが、現代のPHP開発における一般的な依存関係管理の文脈を意識した記述です。

compareDocumentPositionメソッドは、ノード間の位置関係を示す複数のフラグが組み合わされたビットマスクを整数で返します。そのため、結果を評価する際は、単純な等値比較ではなく、ビット演算子&を使って個々のフラグ（例: DOM_DOCUMENT_POSITION_FOLLOWING）の意味を正確に判定する必要があります。引数にはDOMElementやDOMTextなど、様々な種類のDOMノードを渡すことができますが、DOMツリー内での物理的な配置が結果に大きく影響することを理解してください。特にDOMDocumentTypeは、ドキュメントルート要素とは親子関係になく、Disconnectedと判定されることが多いです。DOMDocumentからノードを取得する際、対象のノードが存在しない場合はnullを返す可能性があるため、必ずnullチェックを行い安全にコードを実行してください。また、declare(strict_types=1)により厳格な型チェックが適用されていますので、引数や戻り値の型を厳密に守るように注意が必要です。

DOMノード位置比較の活用


1<?php
2
3/**
4 * PHP 8 DOMDocumentType::compareDocumentPosition のサンプルコードです。
5 *
6 * DOM ノード間の相対的な位置関係を比較する方法を示します。
7 * この関数は、PHP の推奨コーディングスタイルに従い、PHPDoc コメントを適切に使用しています。
8 *
9 * @see https://www.php.net/manual/ja/domdocumenttype.comparedocumentposition.php PHP Manual (DOMDocumentType::compareDocumentPosition)
10 * @see https://www.php.net/manual/ja/domnode.comparedocumentposition.php PHP Manual (DOMNode::compareDocumentPosition)
11 */
12
13/**
14 * 2つのDOMノードの相対的な位置を比較し、その結果を出力します。
15 *
16 * DOMDocumentType::compareDocumentPosition メソッド (実際にはDOMNode::compareDocumentPositionを継承) は、
17 * 指定されたノードとその他のノードのドキュメント内の相対的な位置を比較します。
18 * 戻り値はビットマスクであり、複数の状態を示すことができます。
19 *
20 * @param DOMNode $node1 比較の基準となる最初のノード。
21 * @param DOMNode $node2 比較対象となる2番目のノード。
22 * @return void 結果は直接標準出力されます。
23 */
24function demonstrateCompareDocumentPosition(DOMNode $node1, DOMNode $node2): void
25{
26    echo "--- 比較結果 --- \n";
27    echo "ノード1: '{$node1->nodeName}' (Class: " . get_class($node1) . ", Value: '{$node1->nodeValue}')\n";
28    echo "ノード2: '{$node2->nodeName}' (Class: " . get_class($node2) . ", Value: '{$node2->nodeValue}')\n";
29
30    // DOMDocumentType::compareDocumentPosition は DOMNode::compareDocumentPosition と同じ振る舞いをします。
31    // 引数に DOMNode をとりますが、基準となるノードが DOMDocumentType の場合を主に想定しています。
32    $position = $node1->compareDocumentPosition($node2);
33
34    echo "比較結果 (ビットマスク): " . $position . "\n";
35    echo "意味:\n";
36
37    if ($position === 0) {
38        echo "  - 0: ノード1とノード2は同じノードです。\n";
39    } else {
40        if ($position & DOM_DOCUMENT_POSITION_DISCONNECTED) {
41            echo "  - DOM_DOCUMENT_POSITION_DISCONNECTED (0x01): ノードが異なるドキュメントに属しているか、接続されていない。\n";
42        }
43        if ($position & DOM_DOCUMENT_POSITION_PRECEDING) {
44            echo "  - DOM_DOCUMENT_POSITION_PRECEDING (0x02): ノード2がノード1よりも前に出現する (ドキュメント順)。\n";
45        }
46        if ($position & DOM_DOCUMENT_POSITION_FOLLOWING) {
47            echo "  - DOM_DOCUMENT_POSITION_FOLLOWING (0x04): ノード2がノード1よりも後に出現する (ドキュメント順)。\n";
48        }
49        if ($position & DOM_DOCUMENT_POSITION_CONTAINS) {
50            echo "  - DOM_DOCUMENT_POSITION_CONTAINS (0x08): ノード1がノード2を内包している (ノード1がノード2の親である)。\n";
51        }
52        if ($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
53            echo "  - DOM_DOCUMENT_POSITION_CONTAINED_BY (0x10): ノード1がノード2に内包されている (ノード2がノード1の親である)。\n";
54        }
55        if ($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) {
56            echo "  - DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (0x20): 実装固有の値。\n";
57        }
58    }
59    echo "\n";
60}
61
62// === メイン処理 ===
63// DOMDocumentType のインスタンスを含むDOMツリーを作成します。
64$dom = new DOMDocument();
65$dom->preserveWhiteSpace = false; // 整形を簡単にするため
66$dom->formatOutput = true;       // 整形を簡単にするため
67
68// XML文字列をロードします。ここで <!DOCTYPE ...> 部分が DOMDocumentType ノードになります。
69$xmlString = '<!DOCTYPE root SYSTEM "example.dtd"><root attr="value"><child1/><child2/></root>';
70$dom->loadXML($xmlString);
71
72// DOMDocumentType ノードを取得します。
73$documentType = $dom->doctype;
74if ($documentType === null) {
75    echo "エラー: DOMDocumentType ノードが見つかりませんでした。DTDを含むXMLを使用してください。\n";
76    exit(1);
77}
78
79// 比較対象となる他のノードを取得します。
80$rootElement = $dom->documentElement; // <root>要素
81$child1Element = $dom->getElementsByTagName('child1')->item(0); // <child1>要素
82
83echo "構築されたDOM構造の例:\n";
84echo "  - DOMDocumentType (DOCTYPE root SYSTEM \"example.dtd\")\n";
85echo "  - DOMElement 'root'\n";
86echo "    - DOMElement 'child1'\n";
87echo "    - DOMElement 'child2'\n\n";
88
89
90// --- 様々な比較例 ---
91
92// 1. DOMDocumentType とルート要素の比較:
93//    documentType (ノード1) から見て rootElement (ノード2) は後に来る。
94echo "--- 比較例1: DOMDocumentType と ルート要素 ---\n";
95demonstrateCompareDocumentPosition($documentType, $rootElement);
96
97// 2. ルート要素とDOMDocumentTypeの比較:
98//    rootElement (ノード1) から見て documentType (ノード2) は前に来る。
99echo "--- 比較例2: ルート要素 と DOMDocumentType ---\n";
100demonstrateCompareDocumentPosition($rootElement, $documentType);
101
102// 3. DOMDocumentType と子要素の比較:
103//    documentType (ノード1) から見て child1Element (ノード2) は後に来る。
104echo "--- 比較例3: DOMDocumentType と 子要素 ---\n";
105demonstrateCompareDocumentPosition($documentType, $child1Element);
106
107// 4. 同じノード同士の比較:
108//    同じノードを比較した場合、結果は常に 0 になります。
109echo "--- 比較例4: 同じノード同士の比較 (DOMDocumentType vs DOMDocumentType) ---\n";
110demonstrateCompareDocumentPosition($documentType, $documentType);
111
112// 5. 別のドキュメントのノードとの比較:
113//    異なるDOMDocumentに属するノード同士の比較では、DISCONNECTED (接続されていない) 状態が示されます。
114$anotherDom = new DOMDocument();
115$anotherDom->loadXML('<another_root/>');
116$anotherRoot = $anotherDom->documentElement;
117
118if ($anotherRoot !== null) {
119    echo "--- 比較例5: 異なるドキュメントのノード ---\n";
120    demonstrateCompareDocumentPosition($documentType, $anotherRoot);
121}
122
123?>

PHP 8のDOMDocumentType::compareDocumentPositionメソッドは、DOMツリー内の二つのノードが互いに対してどのような相対的な位置にあるかを比較します。このメソッドはDOMNodeクラスで定義されており、DOMDocumentTypeオブジェクトから呼び出すことで、ドキュメントタイプノードと任意の他のノードの位置関係を調べることが可能です。

引数には比較対象のDOMNodeオブジェクトを渡します。戻り値は整数値で、これはビットマスクとして複数の状態を同時に示します。例えば、両方のノードが同じであれば0を返します。それ以外の場合、呼び出し元のノードから見て引数で指定したノードがドキュメント構造のどこに位置するかによって、DOM_DOCUMENT_POSITION_DISCONNECTED（異なるドキュメントに属する）、DOM_DOCUMENT_POSITION_PRECEDING（前に位置する）、DOM_DOCUMENT_POSITION_FOLLOWING（後に位置する）、DOM_DOCUMENT_POSITION_CONTAINS（呼び出し元が引数を内包する）、DOM_DOCUMENT_POSITION_CONTAINED_BY（呼び出し元が引数に内包される）などの定数の組み合わせが返されます。この機能は、XMLやHTMLドキュメントの複雑な構造を解析し、特定のノードが他のノードに対してどのように配置されているかをプログラムで正確に判断する際に非常に役立ちます。

このメソッドはDOMDocumentTypeクラスに記述されていますが、実際にはDOMNodeクラスで定義されており、任意のDOMノード間の相対的な位置を比較するために利用できます。戻り値は、複数の状態を同時に示すビットマスクです。特定の状態を確認するには、ビット論理積演算子（&）と対応する定数を用いて判定してください。比較するノードが異なるドキュメントに属している場合、結果にはDOM_DOCUMENT_POSITION_DISCONNECTEDが含まれる点に注意が必要です。また、$dom->doctypeプロパティは、読み込んだXMLにDOCTYPE宣言がない場合はnullとなるため、利用前に必ずその存在を確認してください。