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

Copy
1<?php
2
3/**
4 * DOMCdataSection::contains メソッドの使用例を示します。
5 *
6 * DOMCdataSection は XML の CDATA セクションを表すノードです。
7 * その性質上、他のDOMノードを子ノードとして持つことはできません。
8 *
9 * contains メソッドは DOMNode クラスから継承されており、
10 * 通常は「現在のノードが引数として渡されたノードを子孫として含むか」を判定します。
11 * しかし、DOMCdataSection は子ノードを持てないため、
12 * このメソッドは、引数として渡されたノードが自身のインスタンスと
13 * 厳密に同じである場合にのみ true を返し、それ以外は false を返します。
14 *
15 * この例では、キーワード「contains」がDOMの文脈でどのように使用されるかを示します。
16 * （一般的なPHPの配列要素の包含チェックとは異なります。）
17 */
18function demonstrateCdataSectionContains(): void
19{
20    // 1. DOMDocument オブジェクトを作成します。
21    //    XML ドキュメント全体のコンテナとなります。
22    $dom = new DOMDocument('1.0', 'UTF-8');
23    $dom->formatOutput = true; // 出力されるXMLを見やすくするための設定
24
25    // 2. ルート要素を作成し、DOMDocument に追加します。
26    //    例: <root>...</root>
27    $rootElement = $dom->createElement('root');
28    $dom->appendChild($rootElement);
29
30    // 3. DOMCdataSection オブジェクトを作成します。
31    //    CDATAセクションは、特殊文字をエスケープせずにXML内に埋め込むために使用されます。
32    $cdataSection = $dom->createCDATASection('これは <CDATA> セクションのデータです。特殊文字もそのまま扱われます。');
33    // 作成した CDATA セクションをルート要素の子として追加します。
34    $rootElement->appendChild($cdataSection);
35
36    // 4. 比較対象となる別のノードをいくつか作成します。
37    $anotherCdataSection = $dom->createCDATASection('別のCDATAデータ');
38    $textNode = $dom->createTextNode('ただのテキストノード');
39
40    echo "--- DOMCdataSection::contains の使用例 ---\n";
41
42    // ケース1: 自身のノードに対して contains を呼び出す
43    // DOMCdataSection は子ノードを持てないため、自身との比較のみが true を返す可能性があります。
44    echo "cdataSection->contains(\$cdataSection) の結果: ";
45    if ($cdataSection->contains($cdataSection)) {
46        echo "true (ノードは自分自身を含みます)\n";
47    } else {
48        echo "false (このケースでは通常発生しません)\n";
49    }
50
51    // ケース2: 別の DOMCdataSection ノードと比較
52    echo "cdataSection->contains(\$anotherCdataSection) の結果: ";
53    if ($cdataSection->contains($anotherCdataSection)) {
54        echo "true (これは通常発生しません)\n";
55    } else {
56        echo "false (別のCDATAセクションは含まれません)\n";
57    }
58
59    // ケース3: DOMText ノードと比較
60    echo "cdataSection->contains(\$textNode) の結果: ";
61    if ($cdataSection->contains($textNode)) {
62        echo "true (これは通常発生しません)\n";
63    } else {
64        echo "false (テキストノードは含まれません)\n";
65    }
66
67    echo "\n--- 参考: 親要素での contains メソッド ---\n";
68    // 親ノードが子ノード（または子孫ノード）を含むかを確認する一般的な使用例
69    echo "rootElement->contains(\$cdataSection) の結果: ";
70    if ($rootElement->contains($cdataSection)) {
71        echo "true (ルート要素はCDATAセクションを子孫として含みます)\n";
72    } else {
73        echo "false (これは発生しないはず)\n";
74    }
75
76    echo "\n--- 生成された XML の確認 ---\n";
77    echo $dom->saveXML();
78}
79
80// 関数を実行してサンプルコードの動作を確認します。
81demonstrateCdataSectionContains();

DOMCdataSection::containsメソッドは、XMLのCDATAセクションを表すDOMCdataSectionオブジェクトが、引数で指定されたDOMNode $otherを子孫として含んでいるかを判定します。

通常、containsメソッドは現在のノードが引数のノードを子孫として持つかを確認しますが、DOMCdataSectionはその性質上、他のDOMノードを子ノードとして持つことができません。このため、DOMCdataSection::containsは特殊な挙動を示します。具体的には、引数として渡されたDOMNode $otherが、メソッドを呼び出している自身のDOMCdataSectionインスタンスと厳密に同じである場合にのみtrueを返し、それ以外の場合はfalseを返します。

引数$otherは比較対象となるDOMノードであり、戻り値は比較結果を示す真偽値（trueまたはfalse）です。この「contains」は、PHPで配列の要素を検索する一般的なin_arrayのような「含む」という意味合いとは異なり、DOM構造におけるノードの同一性や親子関係を確認する際に使用されるものです。

Copy
1<?php
2
3/**
4 * DOMCdataSection::contains() メソッドの使用例を示します。
5 *
6 * このメソッドは、指定された DOMNode が現在の DOMCdataSection ノードに含まれているかどうかをチェックします。
7 * 具体的には、`$other` ノードが `$cdataSection` ノードの子孫である場合に true を返します。
8 *
9 * PHP 8.3.0 以降で利用可能なメソッドです。
10 * ユーザー指定のリファレンスでは戻り値が「戻り値なし」となっていますが、
11 * PHP公式ドキュメントでは `bool` を返すとされており、このコードはその実際の挙動に従います。
12 *
13 * 注意点: CDATA セクションはテキストノードの一種であり、DOM ツリーにおいて通常は子ノードを持つことはありません。
14 * そのため、`DOMCdataSection::contains()` メソッドが `true` を返すシナリオは非常に稀であり、
15 * ほとんどの場合 `false` を返します。
16 *
17 * @param DOMCdataSection $cdataSection 包含関係をチェックする対象の CDATA セクションノード。
18 * @param DOMNode         $other        $cdataSection に含まれているかをチェックする別のノード。
19 */
20function demonstrateDomCdataSectionContains(DOMCdataSection $cdataSection, DOMNode $other): void
21{
22    echo "--- DOMCdataSection::contains() のデモンストレーション ---\n";
23    echo "CDATAセクションの内容: '" . $cdataSection->data . "'\n";
24    echo "比較対象のノードのタイプ: " . get_class($other) . "\n";
25    if ($other->nodeValue !== null) {
26        echo "比較対象のノードの値: '" . substr($other->nodeValue, 0, 30) . (strlen($other->nodeValue) > 30 ? '...' : '') . "'\n";
27    }
28
29    // DOMCdataSection::contains() は PHP 8.3.0 以降で利用可能です。
30    // このメソッドは、指定されたノードがカレントノードの子孫である場合に true を返します。
31    // しかし、CDATAセクションは子ノードを持たないため、通常は false を返します。
32    $isContained = $cdataSection->contains($other);
33
34    if ($isContained) {
35        echo "結果: 指定されたノードは CDATA セクションに含まれています。\n";
36    } else {
37        echo "結果: 指定されたノードは CDATA セクションに含まれていません。\n";
38    }
39    echo "---------------------------------------------------------\n\n";
40}
41
42// 単体で動作可能なサンプルコード
43// 1. DOMDocument を作成します。
44$dom = new DOMDocument('1.0', 'UTF-8');
45$dom->formatOutput = true; // 出力を整形するため
46
47// 2. ルート要素を作成し、DOMDocument に追加します。
48$rootElement = $dom->createElement('root');
49$dom->appendChild($rootElement);
50
51// 3. CDATA セクションノードを作成し、ルート要素の子として追加します。
52$cdataSection = $dom->createCDATASection('この中に <タグ> や &エンティティ; があってもXMLパーサーは無視します。');
53$rootElement->appendChild($cdataSection);
54
55// 4. 比較対象となる別のノードを作成します。
56$textNode = $dom->createTextNode('これはCDATAセクションとは異なるテキストノードです。');
57$commentNode = $dom->createComment('これはCDATAセクションとは異なるコメントノードです。');
58$childElement = $dom->createElement('child');
59
60// 5. テキストノードと子要素をルート要素の子として追加します。
61//    これにより、これらのノードが CDATA セクションの子孫ではないことが明確になります。
62$rootElement->appendChild($textNode);
63$rootElement->appendChild($childElement);
64
65// 6. demonstrateDomCdataSectionContains 関数を呼び出し、挙動を確認します。
66
67// CDATAセクションと他のテキストノードの比較
68// 結果は false となることを期待します (CDATAセクションは子ノードを持たないため)。
69demonstrateDomCdataSectionContains($cdataSection, $textNode);
70
71// CDATAセクションとコメントノードの比較
72// 結果は false となることを期待します。
73demonstrateDomCdataSectionContains($cdataSection, $commentNode);
74
75// CDATAセクションと子要素の比較
76// 結果は false となることを期待します。
77demonstrateDomCdataSectionContains($cdataSection, $childElement);
78
79// CDATAセクション自身との比較
80// 結果は false となることを期待します (自身は子孫ではないため)。
81demonstrateDomCdataSectionContains($cdataSection, $cdataSection);
82
83// DOMツリーの全体構造を表示 (参考用)
84// echo "DOMツリー:\n";
85// echo $dom->saveXML();
86
87?>

DOMCdataSection::contains()メソッドは、PHPのDOM拡張機能の一部で、あるCDATAセクションノードが別のDOMノードを含んでいるかどうかを判別するために使用されます。引数 $other には、含まれるかどうかを確認したいDOMノードを指定します。このメソッドは、もし $other ノードが現在のCDATAセクションノードの子孫であれば true を、そうでなければ false を返します。提供されたリファレンス情報では「戻り値なし」と記載されていますが、PHPの実際の挙動および公式ドキュメントでは bool 型の値を返します。

しかし、重要な点として、CDATAセクションはXMLやHTML内で特殊文字をエスケープせずに記述するためのテキストノードの一種であり、DOMツリーにおいて通常は子ノードを持つことがありません。このため、DOMCdataSection::contains()メソッドが true を返すシナリオは非常に稀で、ほとんどの場合 false を返します。サンプルコードでは、CDATAセクションと他の様々なノードを比較していますが、予想通り全ての場合で false が返されることを確認できます。このメソッドはPHP 8.3.0以降で利用可能です。