【PHP8.x】compareDocumentPositionメソッドの使い方

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

作成日: 2025年09月11日更新日: 2025年10月30日

基本的な使い方

compareDocumentPositionメソッドは、Dom\Nodeオブジェクトである自身と、引数で渡された別のDom\Nodeオブジェクトとのドキュメントツリー内での相対的な位置関係を比較し、その結果を示す数値を返すメソッドです。ウェブページなどのHTMLやXMLドキュメントをPHPで操作する際に、二つのノードがドキュメント内でどのような順序や親子関係にあるのかを正確に知りたい場合に使用します。

このメソッドは、比較したいDom\Nodeオブジェクトを一つ引数として受け取ります。戻り値は整数値で、これはビットマスクと呼ばれる形式で、複数の位置関係の情報を同時に表現しています。

返される主な値とその意味は以下の通りです。

0: 二つのノードが完全に同じノードであることを示します。
DOM_DOCUMENT_POSITION_DISCONNECTED (値: 1): 二つのノードがドキュメントツリー上で接続されていない、つまり、異なるドキュメントに属しているか、ツリーから切り離されている状態であることを示します。
DOM_DOCUMENT_POSITION_PRECEDING (値: 2): このメソッドが呼び出されたノードが、引数で渡されたノードよりもドキュメント内で前に位置することを示します。
DOM_DOCUMENT_POSITION_FOLLOWING (値: 4): このメソッドが呼び出されたノードが、引数で渡されたノードよりもドキュメント内で後に位置することを示します。
DOM_DOCUMENT_POSITION_CONTAINS (値: 8): このメソッドが呼び出されたノードが、引数で渡されたノードを子孫として包含していることを示します。
DOM_DOCUMENT_POSITION_CONTAINED_BY (値: 16): このメソッドが呼び出されたノードが、引数で渡されたノードに子孫として包含されていることを示します。

これらの値は単独で返されるだけでなく、複数の情報が組み合わされて返されることもあります。例えば、あるノードが別のノードより前にあり、かつそのノードを含んでいる場合などです。開発者はこれらのビットマスクを論理AND演算子などを用いて解析することで、複雑なノード間の位置関係を詳細に把握し、ドキュメント構造に基づいた動的な処理を正確に実装することが可能になります。

構文(syntax)


1<?php
2// DOMDocument インスタンスを作成
3$dom = new DOMDocument();
4
5// 比較対象となるDOMノードを作成
6$parentNode = $dom->createElement('parent');
7$childNode = $dom->createElement('child');
8$siblingNode = $dom->createElement('sibling');
9
10// ノードをDOMツリーに追加して親子関係・兄弟関係を構築
11$dom->appendChild($parentNode); // ドキュメントに親ノードを追加
12$parentNode->appendChild($childNode); // 親ノードに子ノードを追加
13$parentNode->appendChild($siblingNode); // 親ノードに別の兄弟ノードを追加
14
15// compareDocumentPosition メソッドを使用して2つのノードの位置関係を比較します
16// 例: $parentNode を基準として、$childNode がどこにあるかを比較
17$positionBitmask = $parentNode->compareDocumentPosition($childNode);
18
19// 例: $childNode を基準として、$siblingNode がどこにあるかを比較
20// $anotherPositionBitmask = $childNode->compareDocumentPosition($siblingNode);
21
22// 戻り値の $positionBitmask は整数値で、ノード間の相対的な位置関係を示すビットマスクです。
23// （例: DOM_DOCUMENT_POSITION_CONTAINED_BY, DOM_DOCUMENT_POSITION_FOLLOWING など）
24?>

引数(parameters)

Dom\Node $other

Dom\Node $other: 比較対象となるDOMノード

戻り値(return)

int

このメソッドは、2つのDOMノードの文書内での相対的な位置関係を示す整数値を返します。返される値はビットマスクとして解釈され、ノードが同じ文書に属するか、一方のノードがもう一方のノードの前に位置するかなどを表します。