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

Copy
1<?php
2
3/**
4 * @file This script demonstrates the usage of DOMAttr::compareDocumentPosition.
5 *
6 * It uses PHP's DOM extension to parse an XML string and compare the
7 * document position of different nodes, specifically focusing on DOMAttr.
8 *
9 * For beginners aiming to become System Engineers, understanding PHPDoc
10 * comments (for tools like phpdocumentor) and modular code structure
11 * (which Composer helps manage in larger projects) is crucial.
12 */
13
14namespace App\DomExamples;
15
16use DOMDocument;
17use DOMAttr;
18use DOMElement;
19use DOMNode;
20
21/**
22 * Provides an example of how to use DOMAttr::compareDocumentPosition.
23 *
24 * This class encapsulates the logic for demonstrating node comparison
25 * within a DOM document, adhering to good coding practices and PHPDoc.
26 */
27class DomPositionComparer
28{
29    /**
30     * Compares the document position of an attribute node with another DOM node
31     * and outputs a human-readable interpretation of the result.
32     *
33     * The comparison flags (e.g., PRECEDING, FOLLOWING, CONTAINS) indicate
34     * the position of the `$otherNode` relative to the `$attrNode`.
35     *
36     * @param DOMAttr $attrNode  The attribute node to compare from (the "this" node).
37     * @param DOMNode $otherNode The other DOM node to compare against.
38     * @param string  $attrName  A descriptive name for the attribute node (for output clarity).
39     * @param string  $otherName A descriptive name for the other node (for output clarity).
40     * @return void
41     */
42    public function compareAndOutput(DOMAttr $attrNode, DOMNode $otherNode, string $attrName, string $otherName): void
43    {
44        $position = $attrNode->compareDocumentPosition($otherNode);
45
46        echo "Comparing '{$attrName}' with '{$otherName}':\n";
47        echo "  Raw position result: " . $position . "\n";
48
49        // Interpret the bitmask result. The flags indicate the position of $otherNode relative to $attrNode.
50        if ($position === 0) {
51            echo "  Nodes are the same.\n";
52        } else {
53            if (($position & DOM_DOCUMENT_POSITION_DISCONNECTED) > 0) {
54                echo "  - Disconnected (nodes are in different documents or not attached to a tree).\n";
55            }
56            if (($position & DOM_DOCUMENT_POSITION_PRECEDING) > 0) {
57                echo "  - Preceding (otherNode comes *before* attrNode in document order).\n";
58            }
59            if (($position & DOM_DOCUMENT_POSITION_FOLLOWING) > 0) {
60                echo "  - Following (otherNode comes *after* attrNode in document order).\n";
61            }
62            if (($position & DOM_DOCUMENT_POSITION_CONTAINS) > 0) {
63                echo "  - Contains (otherNode is an ancestor of attrNode, meaning otherNode contains attrNode).\n";
64            }
65            if (($position & DOM_DOCUMENT_POSITION_CONTAINED_BY) > 0) {
66                echo "  - Contained By (otherNode is a descendant of attrNode, meaning otherNode is contained within attrNode).\n";
67            }
68            if (($position & DOM_DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC) > 0) {
69                echo "  - Implementation Specific.\n";
70            }
71        }
72        echo "\n";
73    }
74
75    /**
76     * Runs a series of examples demonstrating DOMAttr::compareDocumentPosition
77     * with various node types and relationships.
78     *
79     * @return void
80     */
81    public function runExample(): void
82    {
83        // 1. Create a sample XML document string
84        $xmlString = <<<XML
85<?xml version="1.0" encoding="UTF-8"?>
86<bookstore>
87    <book id="bk101" category="programming">
88        <title lang="en">PHP Basics</title>
89        <author>John Doe</author>
90        <year>2023</year>
91    </book>
92    <book id="bk102" category="web">
93        <title lang="en">HTML &amp; CSS</title>
94        <author>Jane Smith</author>
95        <year>2022</year>
96    </book>
97</bookstore>
98XML;
99
100        // 2. Load the XML into a DOMDocument object
101        $dom = new DOMDocument('1.0', 'UTF-8');
102        // Setting preserveWhiteSpace to false can make navigating simpler by ignoring text nodes that are just whitespace.
103        $dom->preserveWhiteSpace = false;
104        // Setting formatOutput to true makes the output XML look nicer, but doesn't affect comparison logic.
105        $dom->formatOutput = true;
106        $dom->loadXML($xmlString);
107
108        // 3. Get various DOMNodes for comparison
109        /** @var DOMElement $bookElement1 The first book element. */
110        $bookElement1 = $dom->getElementsByTagName('book')->item(0);
111
112        /** @var DOMAttr $idAttr1 The 'id' attribute of the first book element. */
113        $idAttr1 = $bookElement1->getAttributeNode('id');
114
115        /** @var DOMAttr $categoryAttr1 The 'category' attribute of the first book element. */
116        $categoryAttr1 = $bookElement1->getAttributeNode('category');
117
118        /** @var DOMElement $titleElement1 The title element of the first book. */
119        $titleElement1 = $bookElement1->getElementsByTagName('title')->item(0);
120
121        /** @var DOMAttr $langAttr1 The 'lang' attribute of the first book's title element. */
122        $langAttr1 = $titleElement1->getAttributeNode('lang');
123
124        /** @var DOMElement $bookElement2 The second book element. */
125        $bookElement2 = $dom->getElementsByTagName('book')->item(1);
126
127        echo "--- DOMAttr::compareDocumentPosition Examples ---\n\n";
128
129        // Comparison 1: Attribute node with its parent element node
130        // The parent element ($otherNode) contains the attribute ($attrNode) and precedes it.
131        if ($idAttr1 && $bookElement1) {
132            $this->compareAndOutput(
133                $idAttr1,
134                $bookElement1,
135                "book1 'id' attribute",
136                "book1 element (parent)"
137            );
138        }
139
140        // Comparison 2: Attribute node with a sibling attribute node on the same element
141        // The order of attributes in the DOM is implementation-specific but typically follows declaration order.
142        if ($idAttr1 && $categoryAttr1) {
143            $this->compareAndOutput(
144                $idAttr1,
145                $categoryAttr1,
146                "book1 'id' attribute",
147                "book1 'category' attribute (sibling)"
148            );
149        }
150
151        // Comparison 3: Attribute node with an attribute node on a child element
152        // The child element's attribute ($otherNode) comes after the parent element's attribute ($attrNode).
153        if ($idAttr1 && $langAttr1) {
154            $this->compareAndOutput(
155                $idAttr1,
156                $langAttr1,
157                "book1 'id' attribute",
158                "book1 'title lang' attribute (on child)"
159            );
160        }
161
162        // Comparison 4: Attribute node with an element node that is a sibling of its parent
163        // The second book element ($otherNode) comes after the first book's attribute ($attrNode).
164        if ($idAttr1 && $bookElement2) {
165            $this->compareAndOutput(
166                $idAttr1,
167                $bookElement2,
168                "book1 'id' attribute",
169                "book2 element (sibling of parent)"
170            );
171        }
172
173        // Comparison 5: Attribute node with itself
174        // Should return 0, indicating the nodes are identical.
175        if ($idAttr1) {
176            $this->compareAndOutput(
177                $idAttr1,
178                $idAttr1,
179                "book1 'id' attribute",
180                "itself"
181            );
182        }
183
184        // Comparison 6: An attribute node from one document with a newly created, unattached attribute node
185        // These nodes are disconnected as they are not part of the same document tree.
186        $newDom = new DOMDocument();
187        $detachedAttr = $newDom->createAttribute('detached-attr');
188        $detachedAttr->value = 'some-value'; // Value doesn't affect position.
189
190        if ($idAttr1 && $detachedAttr) {
191            $this->compareAndOutput(
192                $idAttr1,
193                $detachedAttr,
194                "book1 'id' attribute",
195                "detached 'detached-attr'"
196            );
197        }
198
199        echo "--- End of Examples ---\n";
200    }
201}
202
203// This block ensures the script can be executed directly from the command line.
204// For larger projects using Composer, you would typically use an autoloader
205// and call this class from an entry point like `index.php` or a command script.
206if (PHP_SAPI === 'cli') {
207    $comparer = new App\DomExamples\DomPositionComparer();
208    $comparer->runExample();
209}

PHP 8のDOMAttr::compareDocumentPositionメソッドは、XMLやHTMLドキュメント内のノード間の相対的な位置関係を特定するために使用されます。このメソッドは、DOMAttrオブジェクト（属性ノード）が基準となり、引数として渡されるDOMNode $otherとの位置を比較します。

戻り値は整数値で、これは複数の状態を組み合わせたビットマスクとして結果を示します。例えば、DOM_DOCUMENT_POSITION_PRECEDINGは比較対象のノードが基準ノードより前に位置すること、DOM_DOCUMENT_POSITION_FOLLOWINGは後に位置することを示します。また、DOM_DOCUMENT_POSITION_CONTAINSは基準ノードが比較対象ノードを内包している状態、DOM_DOCUMENT_POSITION_CONTAINED_BYは基準ノードが比較対象ノードに内包されている状態を表します。ノードが異なるドキュメントに属している場合はDOM_DOCUMENT_POSITION_DISCONNECTEDフラグが設定されます。

サンプルコードでは、XMLドキュメントから複数の属性ノードや要素ノードを取得し、それらを様々な組み合わせで比較しています。例えば、属性ノードとその親要素、異なる要素の属性ノード、あるいは自分自身との比較を通じて、それぞれの位置関係に応じたビットマスク値がどのように変化するかを具体的に示しています。これにより、ドキュメントツリーにおけるノード間の複雑な相対位置をプログラムで正確に判断する方法を学ぶことができます。コード内のPHPDocコメントは、phpdocumentorのようなツールでドキュメントを生成する際に役立ち、大規模プロジェクトでのComposerによる依存関係管理と共に、システムエンジニアとして品質の高いコードを書く上で重要な実践方法を示しています。

Copy
1<?php
2
3/**
4 * DOMAttr::compareDocumentPosition メソッドの使用例を示します。
5 * この関数は、2つのノードの相対的な位置を比較し、
6 * ドキュメントツリー内での関係性を示すビットマスクを返します。
7 * 戻り値はDOM_NODE_DOCUMENT_POSITION_* 定数とビット演算で解釈できます。
8 *
9 * phpDocumentor を使用してこのコードをドキュメント化する際、
10 * このPHPDocブロックが関数の説明として抽出されます。
11 * 適切なドキュメンテーションは、将来のメンテナンスや他の開発者との協力に役立ちます。
12 *
13 * @return void
14 */
15function demonstrateDomAttrCompareDocumentPosition(): void
16{
17    // 1. DOMDocumentを作成し、HTML構造をロードします。
18    // このDOMツリー内のノード間の関係性を比較します。
19    $dom = new DOMDocument();
20    $dom->loadHTML('
21        <div id="container" data-main="true">
22            <p id="first-paragraph" data-item="1">これは最初の段落です。</p>
23            <span id="span-element" data-item="2">これはスパン要素です。</span>
24        </div>
25    ');
26
27    // 2. 比較対象となるDOMAttrインスタンスとDOMNodeインスタンスを取得します。
28    // まず、"container"要素とその属性ノードを取得します。
29    $containerElement = $dom->getElementById('container');
30    if (!$containerElement) {
31        echo "エラー: 'container' 要素が見つかりませんでした。\n";
32        return;
33    }
34    $mainAttr = $containerElement->getAttributeNode('data-main');
35    if (!$mainAttr) {
36        echo "エラー: 'data-main' 属性ノードが見つかりませんでした。\n";
37        return;
38    }
39
40    // 次に、"first-paragraph"要素とその属性ノードを取得します。
41    $paragraphElement = $dom->getElementById('first-paragraph');
42    if (!$paragraphElement) {
43        echo "エラー: 'first-paragraph' 要素が見つかりませんでした。\n";
44        return;
45    }
46    $item1Attr = $paragraphElement->getAttributeNode('data-item');
47    if (!$item1Attr) {
48        echo "エラー: 'data-item' 属性ノードが見つかりませんでした。\n";
49        return;
50    }
51
52    // 別の要素として"span-element"を取得します。
53    $spanElement = $dom->getElementById('span-element');
54    if (!$spanElement) {
55        echo "エラー: 'span-element' 要素が見つかりませんでした。\n";
56        return;
57    }
58
59    echo "--- DOMAttr::compareDocumentPosition の使用例 ---\n";
60    echo "比較元ノード: '{$mainAttr->name}' 属性ノード (親: '{$mainAttr->ownerElement->tagName}')\n\n";
61
62    // 3. 異なるノードとの比較結果を示します。
63    // 比較1: 自身 ('data-main') と比較 (同じノード)
64    echo "1. 自身 ('{$mainAttr->name}') と比較:\n";
65    $result = $mainAttr->compareDocumentPosition($mainAttr);
66    interpretPositionResult($result);
67    echo "\n";
68
69    // 比較2: 子孫要素の属性 ('data-item') と比較
70    // 属性ノードはドキュメントツリーのメイン部分とは異なるため、"Disconnected"が報告されつつも、
71    // ドキュメント順序に基づく関係性も報告されることがあります。
72    echo "2. 子孫要素の属性 ('{$item1Attr->name}') と比較:\n";
73    $result = $mainAttr->compareDocumentPosition($item1Attr);
74    interpretPositionResult($result);
75    echo "\n";
76
77    // 3. 親要素 ('div#container') と比較
78    // ここでも"Disconnected"と、ドキュメント順序および包含関係が同時に報告されることがあります。
79    echo "3. 親要素 ('{$containerElement->tagName}') と比較:\n";
80    $result = $mainAttr->compareDocumentPosition($containerElement);
81    interpretPositionResult($result);
82    echo "\n";
83
84    // 4. 同じ階層にある他の要素 ('span#span-element') と比較
85    echo "4. 同じ階層にある他の要素 ('{$spanElement->tagName}') と比較:\n";
86    $result = $mainAttr->compareDocumentPosition($spanElement);
87    interpretPositionResult($result);
88    echo "\n";
89
90    // 5. ドキュメントノード ($dom) と比較
91    echo "5. ドキュメントノードと比較:\n";
92    $result = $mainAttr->compareDocumentPosition($dom);
93    interpretPositionResult($result);
94    echo "\n";
95}
96
97/**
98 * DOMNode::compareDocumentPosition の結果を解釈し、可読な形式で出力します。
99 * 戻り値はビットマスクであるため、DOM_NODE_DOCUMENT_POSITION_* 定数と
100 * ビット演算子を使用して関係性を判定します。
101 * 複数の関係性が同時に真となる場合（例: 切断されつつも順序関係がある場合など）は、
102 * それらのフラグがOR演算で組み合わされて返されます。
103 *
104 * phpDocumentor を使用してこの関数をドキュメント化する際、
105 * このPHPDocブロックが関数の説明、@param タグが引数の説明として抽出されます。
106 *
107 * @param int $result DOMNode::compareDocumentPosition の戻り値
108 * @return void
109 */
110function interpretPositionResult(int $result): void
111{
112    echo "   結果コード: {$result}\n";
113
114    if ($result === 0) {
115        echo "   -> 2つのノードは同じです。\n";
116        return;
117    }
118
119    $relations = [];
120    if (($result & DOM_NODE_DOCUMENT_POSITION_DISCONNECTED) > 0) {
121        $relations[] = "切断されています (異なるドキュメント、または接続されていないツリー)。";
122    }
123    if (($result & DOM_NODE_DOCUMENT_POSITION_PRECEDING) > 0) {
124        $relations[] = "比較対象ノードが現在のノードの前にあります。";
125    }
126    if (($result & DOM_NODE_DOCUMENT_POSITION_FOLLOWING) > 0) {
127        $relations[] = "比較対象ノードが現在のノードの後にあります。";
128    }
129    if (($result & DOM_NODE_DOCUMENT_POSITION_CONTAINS) > 0) {
130        $relations[] = "現在のノードが比較対象ノードを含んでいます (比較対象ノードが現在のノードの子孫)。";
131    }
132    if (($result & DOM_NODE_DOCUMENT_POSITION_CONTAINED_BY) > 0) {
133        $relations[] = "現在のノードが比較対象ノードに含まれています (比較対象ノードが現在のノードの祖先)。";
134    }
135
136    if (empty($relations)) {
137        echo "   -> 不明な関係性です。\n";
138    } else {
139        foreach ($relations as $relation) {
140            echo "   -> {$relation}\n";
141        }
142    }
143}
144
145// スクリプトの実行
146demonstrateDomAttrCompareDocumentPosition();

PHP 8のDOM拡張機能に属するDOMAttr::compareDocumentPositionメソッドは、XMLやHTMLドキュメント内の2つのノードの相対的な位置関係を比較するために使用されます。このメソッドは、現在のDOMAttr（属性ノード）インスタンスを基準とし、引数として渡された任意のDOMNode $otherとのドキュメントツリー上での位置関係を調べます。

引数$otherには、比較したい要素や別の属性、テキストノードなど、任意のDOMノードを指定します。 メソッドの戻り値はint型の数値で、これは複数の情報を同時に含む「ビットマスク」として解釈されます。具体的には、DOM_NODE_DOCUMENT_POSITION_*という名前の定数（例えば、DOM_NODE_DOCUMENT_POSITION_FOLLOWINGは比較対象が現在のノードの後ろにあることを示す）とビット演算子（&）を使って、ノードが「切断されている（関連がない）」、「前にある」、「後ろにある」、「含んでいる」、「含まれている」といった関係性を判定できます。戻り値が0の場合は、2つのノードが完全に同一であることを意味します。

提供されたサンプルコードでは、まずHTMLから特定の要素とその属性ノードを取得し、その属性ノードを基準として、自身、子孫の属性、親要素、兄弟要素、ドキュメントノードなど、様々な種類のノードと比較しています。これにより、各比較パターンにおける戻り値のビットマスクがどのように変化し、どのような関係性を示しているかが具体的に確認できます。PHPDocコメントは、このようなコードを文書化する際に使用され、開発者間の理解を助ける重要な役割を持ちます。