【PHP8.x】DOMDocumentType::DOCUMENT_POSITION_PRECEDING定数の使い方

Copy
1<?php
2
3/**
4 * DOMNode::compareDocumentPosition() メソッドと
5 * DOMDocumentType::DOCUMENT_POSITION_PRECEDING 定数を用いて、
6 * 2つのDOMノードの相対的な位置関係をデモンストレーションします。
7 *
8 * DOMDocumentType::DOCUMENT_POSITION_PRECEDING は、DOMNode::DOCUMENT_POSITION_PRECEDING と同じ値 (int 2) を持ち、
9 * 比較対象のノードが基準となるノードよりドキュメント順で先行していることを示します。
10 */
11function demonstrateDocumentPositionPreceding(): void
12{
13    // 新しいDOMドキュメントを作成
14    $dom = new DOMDocument();
15    // XMLを整形して出力するため、空白文字の保持を無効にし、フォーマットを有効にする
16    $dom->preserveWhiteSpace = false;
17    $dom->formatOutput = true;
18
19    // サンプルとなるXML構造を読み込む
20    // <root>
21    //   <elementA/>
22    //   <elementB/>
23    // </root>
24    $dom->loadXML('<root><elementA/><elementB/></root>');
25
26    // 比較対象となる2つのノードを取得
27    // getElementsByTagName() は DOMNodeList を返すため、item(0) で最初の要素を取得
28    $elementA = $dom->getElementsByTagName('elementA')->item(0);
29    $elementB = $dom->getElementsByTagName('elementB')->item(0);
30
31    // ノードが正しく取得できたか確認
32    if (!$elementA || !$elementB) {
33        echo "エラー: 'elementA' または 'elementB' ノードが見つかりませんでした。\n";
34        return;
35    }
36
37    echo "--- DOM構造 ---\n";
38    echo $dom->saveXML() . "\n";
39
40    echo "--- ノード位置の比較 ---\n";
41
42    // elementB から見て elementA の位置を比較する
43    // compareDocumentPosition() は、呼び出し元のノード ($elementB) から見て、
44    // 引数のノード ($elementA) がどの位置にあるかを示すビットマスクを返します。
45    $positionResult = $elementB->compareDocumentPosition($elementA);
46
47    echo "比較: elementB->compareDocumentPosition(elementA)\n";
48    echo "  返されたビットマスク値: " . $positionResult . "\n";
49
50    // DOCUMENT_POSITION_PRECEDING 定数 (int 2) を用いて、
51    // elementA が elementB よりドキュメント順で先行しているか判定します。
52    // PHP 8では DOMNode::DOCUMENT_POSITION_PRECEDING のようにクラス名で直接定数にアクセスすることが推奨されます。
53    if (($positionResult & DOMNode::DOCUMENT_POSITION_PRECEDING) === DOMNode::DOCUMENT_POSITION_PRECEDING) {
54        echo "  結果: 'elementA' は 'elementB' よりドキュメント順で先行しています (前にあります)。\n";
55    } else {
56        echo "  結果: 'elementA' は 'elementB' よりドキュメント順で先行していません。\n";
57    }
58
59    echo "\n--- 別の比較例 ---\n";
60
61    // elementA から見て elementB の位置を比較する
62    $positionReverseResult = $elementA->compareDocumentPosition($elementB);
63
64    echo "比較: elementA->compareDocumentPosition(elementB)\n";
65    echo "  返されたビットマスク値: " . $positionReverseResult . "\n";
66
67    // elementB が elementA よりドキュメント順で先行しているか判定します。
68    if (($positionReverseResult & DOMNode::DOCUMENT_POSITION_PRECEDING) === DOMNode::DOCUMENT_POSITION_PRECEDING) {
69        echo "  結果: 'elementB' は 'elementA' よりドキュメント順で先行しています。\n";
70    } else {
71        echo "  結果: 'elementB' は 'elementA' よりドキュメント順で先行していません。\n";
72        echo "    (この場合、'elementB' は 'elementA' の後に続くため、PRECEDING フラグはセットされません。)\n";
73    }
74}
75
76// 関数を実行してデモンストレーションを開始
77demonstrateDocumentPositionPreceding();
78

DOCUMENT_POSITION_PRECEDINGは、PHPのDOM（Document Object Model）拡張機能において、XMLやHTMLのような階層構造を持つドキュメント内の2つのノードの相対的な位置関係を判定するために使用される定数です。この定数の値は整数2であり、あるノードを基準としたとき、比較対象のノードがドキュメントツリー上での記述順で「前に位置している」ことを示します。

主にDOMNodeクラスのcompareDocumentPosition()メソッドと組み合わせて利用されます。compareDocumentPosition()メソッドは、呼び出し元のノードから見て引数のノードがどこにあるかを示すビットマスク（複数の状態を同時に表す整数値）を返します。この戻り値とDOCUMENT_POSITION_PRECEDING定数をビット論理積（&）で比較することで、特定のノードが基準ノードよりドキュメント順で先行しているかどうかを正確に判定できます。

サンプルコードでは、まずelementBを基準としてelementAの位置を比較し、elementAがelementBより先行していることを、この定数を用いて判定しています。次に、elementAを基準としてelementBの位置を比較した際には、elementBはelementAより後に続くため、DOCUMENT_POSITION_PRECEDINGの条件が満たされないことが示されています。この定数はDOMDocumentTypeクラスに所属しますが、実際にはDOMNode::DOCUMENT_POSITION_PRECEDINGとして利用されることが一般的です。

Copy
1<?php
2
3/**
4 * 2つのDOMノードの位置を比較し、最初のノードが2番目のノードより前に来るかどうかを確認します。
5 *
6 * この関数は、グローバル定数 `DOCUMENT_POSITION_PRECEDING` の使用法を示します。
7 * この定数は、参照ノード（最初の引数）が比較対象ノード（2番目の引数）よりも
8 * ドキュメント内で「前に来る」ことを示します。この定数の値は整数です。
9 * `DOMDocumentType` ノードが他の要素ノードより前に配置される場合を例に示します。
10 *
11 * @param DOMNode $node1 比較の基準となる最初のDOMノード。
12 * @param DOMNode $node2 比較対象となる2番目のDOMノード。
13 * @return void
14 */
15function compareNodesForPreceding(DOMNode $node1, DOMNode $node2): void
16{
17    // $node1 の $node2 に対する位置を比較します。
18    // 戻り値は、関係を記述するビットマスクです。
19    // DOCUMENT_POSITION_PRECEDING (整数値 2) は、$node1 が $node2 の前に来ることを示します。
20    // この定数は、一般的に DOMNode::compareDocumentPosition() によって返されます。
21    $positionResult = $node1->compareDocumentPosition($node2);
22
23    echo "--- '{$node1->nodeName}' と '{$node2->nodeName}' の比較 ---\n";
24    echo "比較結果の生の数値: {$positionResult}\n";
25
26    // 結果に DOCUMENT_POSITION_PRECEDING フラグが設定されているかチェックします。
27    // ここではグローバル定数 DOCUMENT_POSITION_PRECEDING を使用しています。
28    // これは DOMNode::DOCUMENT_POSITION_PRECEDING と同じ値です。
29    if (($positionResult & DOCUMENT_POSITION_PRECEDING) === DOCUMENT_POSITION_PRECEDING) {
30        echo "✅ 結果は、「{$node1->nodeName}」が「{$node2->nodeName}」の前に来ることを示しています。\n";
31    } else {
32        echo "❌ 結果は、「{$node1->nodeName}」が「{$node2->nodeName}」の前に来ること示していません。\n";
33        // 必要に応じて、他の関係も表示できます。
34        if (($positionResult & DOCUMENT_POSITION_FOLLOWING) === DOCUMENT_POSITION_FOLLOWING) {
35            echo "   (代わりに、「{$node1->nodeName}」は「{$node2->nodeName}」の後に来ています。)\n";
36        } elseif (($positionResult & DOCUMENT_POSITION_DISCONNECTED) === DOCUMENT_POSITION_DISCONNECTED) {
37            echo "   (ノードは互いに分離されています。)\n";
38        }
39    }
40    echo "\n";
41}
42
43// 1. 新しいDOMドキュメントを作成し、DOCTYPEを持つHTMLを読み込みます。
44$dom = new DOMDocument('1.0', 'UTF-8');
45$dom->formatOutput = true; // 出力整形用ですが、このデモでは直接使用しません。
46
47$htmlContent = <<<HTML
48<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
49<html>
50<head>
51    <title>サンプルページ</title>
52</head>
53<body>
54    <h1>ようこそ</h1>
55    <p>これは段落です。</p>
56</body>
57</html>
58HTML;
59$dom->loadHTML($htmlContent);
60
61// 2. DOMDocumentTypeノードとルートのDOMElementノードを取得します。
62// ドキュメントタイプはドキュメント自体の最初の子供で、ドキュメント要素の前に来ます。
63$documentTypeNode = $dom->doctype; // これは DOMDocumentType のインスタンスです。
64$documentElement = $dom->documentElement; // これは <html> 要素で、DOMElement のインスタンスです。
65$headElement = $dom->getElementsByTagName('head')->item(0); // <html> 内の要素
66
67// 比較する有効なノードがあることを確認します。
68if ($documentTypeNode instanceof DOMDocumentType && $documentElement instanceof DOMElement) {
69    // シナリオ1: DOMDocumentTypeノードが<html>要素の前に来ます。
70    // これは DOCUMENT_POSITION_PRECEDING を示すはずです。
71    compareNodesForPreceding($documentTypeNode, $documentElement);
72
73    // シナリオ2: <html>要素はDOMDocumentTypeノードの前に来ません。
74    // 実際には後に来ます。これは DOCUMENT_POSITION_PRECEDING を示すべきではありません。
75    compareNodesForPreceding($documentElement, $documentTypeNode);
76
77    // シナリオ3: head要素がbody要素の前に来ます（もしあれば）。
78    $bodyElement = $dom->getElementsByTagName('body')->item(0);
79    if ($headElement instanceof DOMElement && $bodyElement instanceof DOMElement) {
80        compareNodesForPreceding($headElement, $bodyElement);
81    } else {
82        echo "追加の比較のためのhead要素またはbody要素が見つかりませんでした。\n";
83    }
84
85} else {
86    echo "エラー: 比較のためにDOMDocumentTypeまたはDOMElementを取得できませんでした。\n";
87}

このコードは、PHPのDOM操作において、2つのDOMノードの相対的な位置を比較する際に利用されるDOCUMENT_POSITION_PRECEDING定数の使用方法を示しています。この定数は整数値を持ち、主にDOMNode::compareDocumentPosition()メソッドの戻り値の一部として使用され、比較対象の最初のノードが2番目のノードよりもドキュメント内で「前に配置されている」という関係を表します。

サンプルコードのcompareNodesForPreceding関数は、比較の基準となるDOMNode型の引数$node1と、比較対象となるDOMNode型の引数$node2を受け取ります。この関数は、$node1の$node2に対する位置をDOMNode::compareDocumentPosition()メソッドで比較します。このメソッドの戻り値は、複数の関係性を示すビットマスク形式の整数値です。関数内では、その比較結果がDOCUMENT_POSITION_PRECEDING定数（値はint型）と一致するかどうかをビットAND演算で確認し、その結果を画面に出力します。この関数の戻り値はvoidであり、比較結果を直接返さずに表示する役割です。

具体例として、HTMLドキュメントの<!DOCTYPE html>を表すDOMDocumentTypeノードと、<html>要素を表すDOMElementノードを比較しています。DOMDocumentTypeノードはドキュメント内で<html>要素の前に位置するため、この比較ではDOCUMENT_POSITION_PRECEDINGが検出され、最初のノードが2番目のノードの前に来ることが確認できます。これにより、DOMツリーにおけるノード間の順序を正確に把握する方法を理解できます。