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

Copy
1<?php
2
3/**
4 * DOMEntityReference ノードの比較と結果に基づいたエラーチェックの例。
5 *
6 * この関数は、2つの DOMEntityReference ノードを比較し、
7 * 期待される結果と実際の比較結果が異なる場合に、
8 * その状態を「エラー」として報告します。
9 * ここでいう「エラー」は、PHPの実行時エラーではなく、
10 * アプリケーションのビジネスロジックにおいて期待と異なる状態が発生したことを指します。
11 *
12 * @param DOMDocument $dom DOMDocument オブジェクト
13 * @param string $entityName1 最初のエンティティ参照の名前
14 * @param string $entityName2 2番目のエンティティ参照の名前
15 * @param bool $expectedEquality 2つのノードが等しいと期待されるか
16 * @return void
17 */
18function compareDomEntityReferencesWithErrorCheck(
19    DOMDocument $dom,
20    string $entityName1,
21    string $entityName2,
22    bool $expectedEquality
23): void {
24    // DOMEntityReference オブジェクトを作成します。
25    // PHP 8では、DOMDocument::createEntityReference() メソッドを使用してエンティティ参照を作成できます。
26    $node1 = $dom->createEntityReference($entityName1);
27    $node2 = $dom->createEntityReference($entityName2);
28
29    // isEqualNode() メソッドを使用してノードを比較します。
30    // このメソッドは、ノードの型、名前、値、属性などが同じであれば true を返します。
31    // DOMEntityReference の場合、主にエンティティ名（nodeName）が比較の対象となります。
32    $areEqual = $node1->isEqualNode($node2);
33
34    echo "--- 比較結果 ---\n";
35    echo "エンティティ1: '" . $entityName1 . "'\n";
36    echo "エンティティ2: '" . $entityName2 . "'\n";
37    echo "isEqualNode() の結果: " . ($areEqual ? 'true' : 'false') . "\n";
38    echo "期待される結果: " . ($expectedEquality ? 'true' : 'false') . "\n";
39
40    // 期待される結果と実際の比較結果をチェックし、異なる場合は「エラー」として報告します。
41    if ($areEqual !== $expectedEquality) {
42        echo "!!! エラー: 比較結果が期待と異なります。\n";
43        echo "これは、アプリケーションのロジック上で予期しない状態を示します。\n";
44    } else {
45        echo "比較結果は期待通りです。\n";
46    }
47    echo "----------------\n\n";
48}
49
50// 新しい DOMDocument を作成します。
51// DOMEntityReference の作成には DOMDocument オブジェクトが必要です。
52$dom = new DOMDocument();
53
54// --- サンプル実行 ---
55
56// 例1: 等しいエンティティ参照の比較（期待通り true）
57// 「amp」と「amp」は等しいエンティティ名なので、isEqualNode() は true を返し、期待通りと判断されます。
58compareDomEntityReferencesWithErrorCheck($dom, 'amp', 'amp', true);
59
60// 例2: 異なるエンティティ参照の比較（期待通り false）
61// 「amp」と「gt」は異なるエンティティ名なので、isEqualNode() は false を返し、期待通りと判断されます。
62compareDomEntityReferencesWithErrorCheck($dom, 'amp', 'gt', false);
63
64// 例3: 等しいと期待したが、実際は異なるエンティティ参照の比較
65// 「amp」と「lt」は異なるにもかかわらず、等しいと期待しています。
66// この場合、isEqualNode() は false を返しますが、期待は true なので「エラー」として報告されます。
67compareDomEntityReferencesWithErrorCheck($dom, 'amp', 'lt', true); // 意図的に期待を誤らせて「エラー」発生をデモンストレーション
68
69// 例4: 異なるノードタイプとの比較 (DOMEntityReference と DOMElement)
70// DOMEntityReference::isEqualNode() は引数に ?DOMNode を取るため、DOMElement など他のノードも渡せます。
71echo "--- 異なるノードタイプの比較 ---\n";
72// DOMEntityReference オブジェクトを作成
73$nodeA = $dom->createEntityReference('test');
74// DOMElement オブジェクトを作成
75$nodeB = $dom->createElement('test');
76
77// 異なるノードタイプの比較を実行
78$areNodesEqualDifferentType = $nodeA->isEqualNode($nodeB);
79
80echo "ノードA (DOMEntityReference): 'test'\n";
81echo "ノードB (DOMElement): 'test'\n";
82echo "isEqualNode() の結果: " . ($areNodesEqualDifferentType ? 'true' : 'false') . "\n";
83
84// DOMEntityReference と DOMElement はノードタイプが異なるため、
85// isEqualNode() は常に false を返します。これが期待される結果です。
86$expectedDifferentTypeEquality = false;
87echo "期待される結果: " . ($expectedDifferentTypeEquality ? 'true' : 'false') . "\n";
88
89if ($areNodesEqualDifferentType !== $expectedDifferentTypeEquality) {
90    echo "!!! エラー: 比較結果が期待と異なります。\n";
91    echo "DOMEntityReference と DOMElement のような異なるノードタイプは、通常、等しいとは見なされません。\n";
92} else {
93    echo "比較結果は期待通りです。\n";
94}
95echo "--------------------------\n";
96
97?>

PHP 8 の DOMEntityReference クラスに属する isEqualNode メソッドは、XMLドキュメント内で定義されたエンティティ参照を表すノード同士が、その内容において「等しい」かどうかを比較するためのものです。このメソッドは、引数として比較対象となる別の DOMNode オブジェクト（$otherNode）を受け取ります。この $otherNode には、null を渡すことも可能です。

isEqualNode メソッドは、比較対象のノードと現在のノードの型、名前、値、属性などが全て同じである場合に true を、一つでも異なる点があれば false を戻り値として返します。特に DOMEntityReference の場合、主にエンティティ名（nodeName）が比較の対象となります。異なるノードタイプ（例: DOMEntityReference と DOMElement）を比較した場合も、ノードの型が異なるため、このメソッドは false を返します。

サンプルコードでは、この isEqualNode メソッドを用いて2つのエンティティ参照ノードを比較する基本的な使い方を示しています。さらに、比較結果が期待通りの値であるかを確認することで、アプリケーションのロジック上で予期しない状態、すなわち「エラー」が発生していないかをチェックする応用例も紹介しています。これはPHPの実行時エラーではなく、ビジネスロジック上の期待値と実際の動作が異なる状況を指します。異なるエンティティ名や異なるノードタイプを比較した場合の動作も確認できます。

Copy
1<?php
2
3/**
4 * DOMEntityReference::isEqualNode メソッドの使用例を示します。
5 *
6 * この関数は、XML文字列からDOMを構築し、DOMEntityReference ノードを抽出して
7 * isEqualNode メソッドでノードの論理的な等価性を比較します。
8 * また、キーワード「isset」の関連性として、比較対象のノードが有効であるかを
9 * 事前に確認する一般的なPHPのパターンを示します。
10 */
11function demonstrateDomEntityReferenceComparison(): void
12{
13    // 比較の対象となるXML文字列を定義します。
14    // 同じエンティティ参照を複数回、異なるエンティティ参照、そしてテキストノードを含めます。
15    $xmlString = <<<XML
16<!DOCTYPE doc [
17  <!ENTITY common "この共通エンティティのコンテンツです。">
18  <!ENTITY unique "この独自のエンティティのコンテンツです。">
19]>
20<root>
21  <paragraph>&common;</paragraph>
22  <span>&common;</span>
23  <article>&unique;</article>
24  <plainText>これはただのテキストノードです。</plainText>
25</root>
26XML;
27
28    $dom = new DOMDocument();
29    // XML文字列を読み込みます。エラーが発生した場合は処理を中断します。
30    if (!@$dom->loadXML($xmlString)) {
31        echo "XMLの読み込みに失敗しました。\n";
32        return;
33    }
34
35    // 比較対象となるDOMEntityReferenceノードおよびその他のノードを初期化します。
36    $commonEntityRef1 = null;
37    $commonEntityRef2 = null;
38    $uniqueEntityRef = null;
39    $plainTextNode = null;
40
41    // XMLツリーを走査し、必要なノードを抽出します。
42    foreach ($dom->getElementsByTagName('*') as $elementNode) {
43        foreach ($elementNode->childNodes as $childNode) {
44            if ($childNode instanceof DOMEntityReference) {
45                // エンティティ名でノードを識別し、変数に格納します。
46                if ($childNode->nodeName === 'common') {
47                    if ($commonEntityRef1 === null) {
48                        $commonEntityRef1 = $childNode;
49                    } else {
50                        $commonEntityRef2 = $childNode;
51                    }
52                } elseif ($childNode->nodeName === 'unique') {
53                    $uniqueEntityRef = $childNode;
54                }
55            } elseif ($childNode instanceof DOMText && $elementNode->nodeName === 'plainText') {
56                $plainTextNode = $childNode;
57            }
58        }
59    }
60
61    echo "--- DOMEntityReference::isEqualNode の使用例 ---\n\n";
62
63    // isset を使用して、比較対象のノードが実際に取得できたかを確認します。
64    // これは、null参照によるエラーを防ぐための一般的なプラクティスです（Qiitaなどで頻繁に見られます）。
65    if (isset($commonEntityRef1)) {
66        echo "■ commonEntityRef1が見つかりました (エンティティ名: {$commonEntityRef1->nodeName})。\n";
67
68        // 同じエンティティを参照する別のノードとの比較
69        if (isset($commonEntityRef2)) {
70            echo "  commonEntityRef2が見つかりました (エンティティ名: {$commonEntityRef2->nodeName})。\n";
71            echo "  commonEntityRef1 と commonEntityRef2 を比較します。\n";
72            // 同じ論理的な内容（同じエンティティ参照）を持つため、trueを返すはずです。
73            $areSameCommonRefs = $commonEntityRef1->isEqualNode($commonEntityRef2);
74            echo "  論理的に等しいですか？ " . ($areSameCommonRefs ? "はい" : "いいえ") . " (期待値: はい)\n\n";
75        } else {
76            echo "  commonEntityRef2が見つかりませんでした。\n\n";
77        }
78
79        // 異なるエンティティを参照するノードとの比較
80        if (isset($uniqueEntityRef)) {
81            echo "  uniqueEntityRefが見つかりました (エンティティ名: {$uniqueEntityRef->nodeName})。\n";
82            echo "  commonEntityRef1 と uniqueEntityRef を比較します。\n";
83            // 異なるエンティティを参照しているため、falseを返すはずです。
84            $areDifferentEntityRefs = $commonEntityRef1->isEqualNode($uniqueEntityRef);
85            echo "  論理的に等しいですか？ " . ($areDifferentEntityRefs ? "はい" : "いいえ") . " (期待値: いいえ)\n\n";
86        } else {
87            echo "  uniqueEntityRefが見つかりませんでした。\n\n";
88        }
89
90        // 異なる型のノード (DOMText) との比較
91        if (isset($plainTextNode)) {
92            echo "  plainTextNodeが見つかりました (ノード型: {$plainTextNode->nodeName})。\n";
93            echo "  commonEntityRef1 と plainTextNode を比較します。\n";
94            // ノードの型が異なるため、falseを返すはずです。
95            $areEntityAndTextEqual = $commonEntityRef1->isEqualNode($plainTextNode);
96            echo "  論理的に等しいですか？ " . ($areEntityAndTextEqual ? "はい" : "いいえ") . " (期待値: いいえ)\n\n";
97        } else {
98            echo "  plainTextNodeが見つかりませんでした。\n\n";
99        }
100
101        // isEqualNodeの引数にnullを渡した場合の動作
102        echo "  commonEntityRef1 と null を比較します。\n";
103        // isEqualNodeはnullを受け付けますが、異なるノードと判断されるためfalseを返します。
104        $isEqualWithNull = $commonEntityRef1->isEqualNode(null);
105        echo "  論理的に等しいですか？ " . ($isEqualWithNull ? "はい" : "いいえ") . " (期待値: いいえ)\n\n";
106
107    } else {
108        echo "commonEntityRef1が見つかりませんでした。XML構造を確認してください。\n";
109    }
110}
111
112// 関数を実行して、DOMEntityReference::isEqualNodeの動作を確認します。
113demonstrateDomEntityReferenceComparison();

DOMEntityReference::isEqualNodeメソッドは、PHPのDOM拡張機能において、XMLやHTMLのDOMツリー上の二つのノードが「論理的に等しいか」を判断するために利用されます。ここでいう「論理的に等しい」とは、ノードの型、名前、値、属性、コンテンツなどが同一であることを意味し、メモリ上で完全に同じオブジェクトであるか（物理的な同一性）とは異なります。

このメソッドは、引数として比較対象となる?DOMNode $otherNodeを受け取ります。この引数はDOMNodeオブジェクト、またはnullを指定できます。戻り値はbool型で、二つのノードが論理的に等しければtrueを、そうでなければfalseを返します。例えば、同じエンティティ定義を参照する複数のDOMEntityReferenceノードは論理的に等しいと判断されますが、異なるエンティティを参照するノードや、ノードの型が異なる場合、あるいは比較対象がnullの場合は等しくないと判断されます。

サンプルコードでは、XML文字列からDOMを構築し、同じエンティティを参照する複数のDOMEntityReferenceノードや異なる型のノードを抽出し、それらの論理的な等価性をisEqualNodeメソッドで検証する過程を示しています。また、比較対象のノードが実際に有効なオブジェクトとして存在しているか、nullでないかをisset関数で確認するPHPの一般的なプログラミングパターンも取り入れています。これは、Qiitaなどの技術記事でもよく見かける、プログラムの安全性を高めるための良い実践方法です。