【PHP8.x】Dom\EntityReference::DOCUMENT_POSITION_FOLLOWING定数の使い方

Copy
1<?php
2
3/**
4 * PHP DOMのノード位置比較の例
5 *
6 * DOMNode::compareDocumentPosition() メソッドを使用して、
7 * 2つのDOMノード間の相対的な位置関係を判断する方法を示します。
8 * 'DOM_DOCUMENT_POSITION_FOLLOWING' (後に続く) と
9 * 'DOM_DOCUMENT_POSITION_PRECEDING' (前に来る) の概念を理解するのに役立ちます。
10 *
11 * 注: ここで示される 'DOM_DOCUMENT_POSITION_FOLLOWING' や
12 *     'DOM_DOCUMENT_POSITION_PRECEDING' は、DOMNode クラスのメソッド
13 *     (compareDocumentPosition) の結果を解釈するためのグローバル定数であり、
14 *     Dom\EntityReference クラスに直接定義されているわけではありません。
15 *     しかし、ドキュメント内のノード位置関係を示す概念として密接に関連しています。
16 */
17function demonstrateDocumentPositionComparison(): void
18{
19    // 1. DOMDocumentを作成し、整形して出力するように設定
20    $dom = new DOMDocument('1.0', 'UTF-8');
21    $dom->formatOutput = true;
22
23    // 2. ルート要素 'root' を追加
24    $root = $dom->createElement('root');
25    $dom->appendChild($root);
26
27    // 3. 子要素 'nodeA' と 'nodeB' を追加
28    $nodeA = $dom->createElement('nodeA');
29    $root->appendChild($nodeA);
30
31    $nodeB = $dom->createElement('nodeB');
32    $root->appendChild($nodeB);
33
34    // 4. 'nodeA' の子要素 'nodeC' を追加
35    $nodeC = $dom->createElement('nodeC');
36    $nodeA->appendChild($nodeC);
37
38    // 5. 'nodeA' の別の(nodeCの兄弟)子要素 'nodeD' を追加
39    $nodeD = $dom->createElement('nodeD');
40    $nodeA->appendChild($nodeD);
41
42    echo "--- DOMノードの位置関係比較デモンストレーション ---\n";
43    echo "ここでは、`\$thisNode->compareDocumentPosition(\$otherNode)` を使って、\n";
44    echo "`\$otherNode` が `\$thisNode` に対してどのように位置するかを判断します。\n\n";
45
46    // 比較 1: nodeA と nodeB
47    // HTML構造: <root><nodeA/><nodeB/></root>
48    // nodeB は nodeA の後に続く
49    $positionAB = $nodeA->compareDocumentPosition($nodeB);
50    echo "比較: \$thisNode=nodeA ($nodeA->nodeName) と \$otherNode=nodeB ($nodeB->nodeName)\n";
51    echo "  - nodeB は nodeA の後に来ますか？\n";
52    if ($positionAB & DOM_DOCUMENT_POSITION_FOLLOWING) {
53        echo "    - はい、nodeB は nodeA の後に来ます。(DOM_DOCUMENT_POSITION_FOLLOWING)\n";
54    } else {
55        echo "    - いいえ、nodeB は nodeA の後に来ません。\n";
56    }
57    echo "  - nodeB は nodeA の前に来ますか？\n";
58    if ($positionAB & DOM_DOCUMENT_POSITION_PRECEDING) {
59        echo "    - はい、nodeB は nodeA の前に来ます。(これは誤り)\n";
60    } else {
61        echo "    - いいえ、nodeB は nodeA の前に来ません。\n";
62    }
63    echo "  (期待される結果: nodeB は nodeA の後に来る)\n\n";
64
65    // 比較 2: nodeB と nodeA (順序を逆転)
66    // HTML構造: <root><nodeA/><nodeB/></root>
67    // nodeA は nodeB の前に来る
68    $positionBA = $nodeB->compareDocumentPosition($nodeA);
69    echo "比較: \$thisNode=nodeB ($nodeB->nodeName) と \$otherNode=nodeA ($nodeA->nodeName)\n";
70    echo "  - nodeA は nodeB の後に来ますか？\n";
71    if ($positionBA & DOM_DOCUMENT_POSITION_FOLLOWING) {
72        echo "    - はい、nodeA は nodeB の後に来ます。(これは誤り)\n";
73    } else {
74        echo "    - いいえ、nodeA は nodeB の後に来ません。\n";
75    }
76    echo "  - nodeA は nodeB の前に来ますか？\n";
77    if ($positionBA & DOM_DOCUMENT_POSITION_PRECEDING) {
78        echo "    - はい、nodeA は nodeB の前に来ます。(DOM_DOCUMENT_POSITION_PRECEDING)\n";
79    } else {
80        echo "    - いいえ、nodeA は nodeB の前に来ません。\n";
81    }
82    echo "  (期待される結果: nodeA は nodeB の前に来る)\n\n";
83
84    // 比較 3: nodeA と nodeC (親と子)
85    // HTML構造: <root><nodeA><nodeC/></nodeA></root>
86    // nodeC は nodeA の子であり、nodeA に包含される。ドキュメント順序では nodeA の後に続く。
87    $positionAC = $nodeA->compareDocumentPosition($nodeC);
88    echo "比較: \$thisNode=nodeA ($nodeA->nodeName) と \$otherNode=nodeC ($nodeC->nodeName)\n";
89    echo "  - nodeC は nodeA の後に来ますか？\n";
90    if ($positionAC & DOM_DOCUMENT_POSITION_FOLLOWING) {
91        echo "    - はい、nodeC は nodeA の後に来ます。\n";
92    } else {
93        echo "    - いいえ、nodeC は nodeA の後に来ません。\n";
94    }
95    echo "  - nodeC は nodeA に包含されますか？\n";
96    if ($positionAC & DOM_DOCUMENT_POSITION_CONTAINED_BY) {
97        echo "    - はい、nodeC は nodeA に包含されます。(DOM_DOCUMENT_POSITION_CONTAINED_BY)\n";
98    } else {
99        echo "    - いいえ、nodeC は nodeA に包含されません。\n";
100    }
101    echo "  (期待される結果: nodeC は nodeA の後に来て、かつ nodeA に包含される)\n\n";
102
103    // 比較 4: nodeD と nodeC (兄弟ノード)
104    // HTML構造: <root><nodeA><nodeC/><nodeD/></nodeA></root>
105    // nodeC は nodeD の前に来る
106    $positionDC = $nodeD->compareDocumentPosition($nodeC);
107    echo "比較: \$thisNode=nodeD ($nodeD->nodeName) と \$otherNode=nodeC ($nodeC->nodeName)\n";
108    echo "  - nodeC は nodeD の後に来ますか？\n";
109    if ($positionDC & DOM_DOCUMENT_POSITION_FOLLOWING) {
110        echo "    - はい、nodeC は nodeD の後に来ます。(これは誤り)\n";
111    } else {
112        echo "    - いいえ、nodeC は nodeD の後に来ません。\n";
113    }
114    echo "  - nodeC は nodeD の前に来ますか？\n";
115    if ($positionDC & DOM_DOCUMENT_POSITION_PRECEDING) {
116        echo "    - はい、nodeC は nodeD の前に来ます。(DOM_DOCUMENT_POSITION_PRECEDING)\n";
117    } else {
118        echo "    - いいえ、nodeC は nodeD の前に来ません。\n";
119    }
120    echo "  (期待される結果: nodeC は nodeD の前に来る)\n\n";
121}
122
123// 関数を実行してデモンストレーションを開始
124demonstrateDocumentPositionComparison();

このPHPサンプルコードは、XMLやHTMLなどのドキュメント構造を操作するDOMにおいて、二つのノードの相対的な位置関係を判断する方法を提示しています。具体的には、DOMNode::compareDocumentPosition() メソッドを使用して、基準となるノードに対して別のノードがドキュメント内でどこに位置するかを比較します。このメソッドは、比較結果をビットマスクとして整数値で返します。

DOM_DOCUMENT_POSITION_FOLLOWING は、比較対象のノードが基準ノードの「後に続く」場合に、DOM_DOCUMENT_POSITION_PRECEDING は「前に来る」場合に、それぞれ compareDocumentPosition() メソッドの戻り値に含まれる定数です。これらの定数はPHPのDOM操作におけるグローバル定数であり、ビット演算子 (&) を使って戻り値に含まれる特定の状態を判定するために用いられます。

サンプルコードでは、まず複数のDOM要素（nodeA, nodeB, nodeC, nodeD など）を作成し、それぞれ異なる組み合わせで位置比較を行っています。例えば、nodeA と nodeB の比較では、nodeB が nodeA の物理的な後に続くため、結果に DOM_DOCUMENT_POSITION_FOLLOWING が含まれることを確認できます。これにより、DOMノードの位置関係の概念と、それをプログラムで判定する方法を具体的に理解することができます。

Copy
1<?php
2
3use Dom\EntityReference; // Dom\EntityReference クラスの定数を使用
4use DOMDocument;
5use DOMElement;
6
7/**
8 * 二つのDOMノードの位置関係を比較し、一方のノードがもう一方のノードの後に来るかどうかを判定します。
9 *
10 * この関数はPHPDocの `@param` タグの使用例と、DOM操作におけるノード位置比較の概念を示します。
11 * 引数は、例えばウェブフォームから送られたデータ（POSTリクエストのパラメータ）として、
12 * 処理対象のノードを識別するために使用されることを想定しています。
13 *
14 * @param string $firstNodeIdentifier  比較対象となる最初のノードを識別するための文字列。
15 * @param string $secondNodeIdentifier 比較対象となる2番目のノードを識別するための文字列。
16 * @return string ノードの位置関係に関する説明文字列を返します。
17 */
18function compareDomNodePositions(string $firstNodeIdentifier, string $secondNodeIdentifier): string
19{
20    // PHP 8のリファレンス情報に従い、Dom\EntityReference::DOCUMENT_POSITION_FOLLOWING 定数を使用します。
21    // この定数は、ノードが比較対象のノードの「後に続く」位置にあることを示します。
22    // Dom\EntityReference は Dom\Node を継承しているため、その定数は Dom\Node の定数と同一の値を持ち、
23    // DOMElement のような一般的なDOMノードの比較にも適用できます。
24
25    // 簡潔な例を示すため、ダミーのDOM要素を作成します。
26    // 実際には、$firstNodeIdentifier や $secondNodeIdentifier を基に、
27    // 既存のDOMツリーから実際のDom\Nodeオブジェクト（例: Dom\Element）を取得します。
28    $dom = new DOMDocument();
29    $root = $dom->createElement('root');
30    $nodeA = $dom->createElement('nodeA', 'First Node Content');
31    $nodeB = $dom->createElement('nodeB', 'Second Node Content');
32
33    $dom->appendChild($root);
34    $root->appendChild($nodeA);
35    $root->appendChild($nodeB); // この配置では nodeB は nodeA の後に続きます
36
37    // ここで、nodeB が nodeA の後に続いているか比較します。
38    // compareDocumentPosition() メソッドは、呼び出し元のノード（$nodeB）が引数のノード（$nodeA）に対して
39    // どのような位置関係にあるかをビットマスクで返します。
40    $comparisonResult = $nodeB->compareDocumentPosition($nodeA);
41
42    // Dom\EntityReference::DOCUMENT_POSITION_FOLLOWING 定数を使って、
43    // 結果に「後に続く」という位置関係が含まれているかをチェックします。
44    if (($comparisonResult & EntityReference::DOCUMENT_POSITION_FOLLOWING) === EntityReference::DOCUMENT_POSITION_FOLLOWING) {
45        return "識別子 '{$secondNodeIdentifier}' のノード（例: nodeB）は、識別子 '{$firstNodeIdentifier}' のノード（例: nodeA）の後に続いています。";
46    } else {
47        return "識別子 '{$secondNodeIdentifier}' のノード（例: nodeB）は、識別子 '{$firstNodeIdentifier}' のノード（例: nodeA）の後に続いていません。";
48    }
49}
50
51// システムエンジニアを目指す初心者向けに、単体で動作可能な使用例を提供します。
52// ここでは、HTTP POSTリクエストで送られてきたかのようなノード識別子を模擬しています。
53$identifierFromPost1 = "product_description_node";
54$identifierFromPost2 = "product_image_node";
55
56$outputMessage = compareDomNodePositions($identifierFromPost1, $identifierFromPost2);
57echo $outputMessage . "\n";
58
59// 別の比較例：ノードが後に続かない場合
60$dom2 = new DOMDocument();
61$root2 = $dom2->createElement('root');
62$child1 = $dom2->createElement('child1');
63$child2 = $dom2->createElement('child2');
64
65$dom2->appendChild($root2);
66$root2->appendChild($child2); // child2 を先に配置
67$root2->appendChild($child1); // child1 を後に配置
68
69// この場合、child2 は child1 の後に続いていない（child1 が child2 の後に続いている）
70$comparisonResultInverse = $child2->compareDocumentPosition($child1);
71if (($comparisonResultInverse & EntityReference::DOCUMENT_POSITION_FOLLOWING) === EntityReference::DOCUMENT_POSITION_FOLLOWING) {
72    echo "要素 'child2' は要素 'child1' の後に続きます。\n";
73} else {
74    echo "要素 'child2' は要素 'child1' の後に続きません。（実際にはchild1がchild2の後に続く関係です）\n";
75}
76

このPHPサンプルコードは、DOM（Document Object Model）における二つのノードの位置関係を比較する方法を、システムエンジニアを目指す初心者にも分かりやすく示しています。PHP 8で利用できる Dom\EntityReference::DOCUMENT_POSITION_FOLLOWING 定数を使って、あるノードが別のノードの「後に続く」位置にあるかどうかを判定する例です。

compareDomNodePositions 関数は、$firstNodeIdentifier と $secondNodeIdentifier という二つの文字列を引数として受け取ります。これらの引数は、ウェブフォームから送られてくるHTTP POSTリクエストのパラメータのように、比較対象となるDOMノードを特定するための識別子を模擬しています。関数内部では、簡単なDOMツリーを作成し、DOMElement オブジェクトが持つ compareDocumentPosition() メソッドを用いてノードの前後関係をビットマスク形式で取得します。そして、この結果を Dom\EntityReference::DOCUMENT_POSITION_FOLLOWING 定数と比較することで、第二のノードが第一のノードの後に続いているかを判断します。関数の戻り値は、この比較結果に応じた説明文の文字列です。

コードの上部にある /** ... */ で囲まれた部分はPHPDocコメントと呼ばれ、関数の目的や引数、戻り値について説明する役割があります。特に @param タグは、引数の名前、型、そしてその役割を記述するために使われ、コードの可読性を高める重要な要素です。