【PHP8.x】Dom\Text::insertBefore()メソッドの使い方

Copy
1<?php
2
3/**
4 * Dom\Text::insertBefore メソッドの利用例を示します。
5 *
6 * このメソッドは実際には Dom\Node クラス（Dom\Text も継承しています）に属し、
7 * 親ノードに対して呼び出され、新しいノード（テキストノードを含む）を
8 * 特定の既存の子ノードの前に挿入するために使用されます。
9 *
10 * システムエンジニアを目指す初心者の方へ:
11 * HTMLやXMLなどの文書構造をプログラムで操作する際に、
12 * 新しい要素やテキストを既存の場所に追加したり、並び替えたりするのに使います。
13 * 例えば、「こんにちは」と「世界」というテキストの間に「素晴らしい」という言葉を挿入するような場合です。
14 */
15function demonstrateDomTextInsertBefore(): void
16{
17    // 1. 新しい Dom\Document オブジェクトを作成します。
18    //    これはHTMLやXML文書全体を表すオブジェクトです。
19    $dom = new Dom\Document('1.0', 'UTF-8');
20    $dom->formatOutput = true; // 生成されるXML/HTMLを見やすく整形します。
21
22    // 2. ルート要素 (<data>) を作成し、文書に追加します。
23    $rootElement = $dom->createElement('data');
24    $dom->appendChild($rootElement);
25
26    // 3. 親となる段落要素 (<p>) を作成し、ルート要素の子として追加します。
27    $paragraphElement = $dom->createElement('p');
28    $rootElement->appendChild($paragraphElement);
29
30    // 4. 既存のテキストノードを作成し、段落要素の子として追加します。
31    //    これが新しいテキストを挿入する「基準」となるノードです。
32    $existingText = $dom->createTextNode('既存のテキストです。');
33    $paragraphElement->appendChild($existingText);
34
35    // 現時点でのDOM構造イメージ:
36    // <data>
37    //   <p>既存のテキストです。</p>
38    // </data>
39
40    // 5. 挿入したい新しいテキストノードを作成します。
41    $newTextToInsert = $dom->createTextNode('ここに新しいテキストを挿入します。');
42
43    // 6. 親要素 ($paragraphElement) の insertBefore メソッドを呼び出します。
44    //    - 第1引数 ($newTextToInsert): 挿入したい新しいノード。
45    //    - 第2引数 ($existingText): どのノードの「前」に挿入するかを指定する既存の子ノード。
46    //    この操作により、$newTextToInsert が $existingText の前に挿入されます。
47    $paragraphElement->insertBefore($newTextToInsert, $existingText);
48
49    // 7. 最終的なDOM構造をXML形式で出力して確認します。
50    echo "--- 生成されたDOM構造 ---\n";
51    echo $dom->saveXML();
52
53    echo "\n--- 期待される出力 ---\n";
54    echo "<data>\n  <p>ここに新しいテキストを挿入します。既存のテキストです。</p>\n</data>\n";
55}
56
57// 関数を実行して動作を確認します。
58demonstrateDomTextInsertBefore();
59

Dom\Node::insertBeforeメソッドは、HTMLやXMLなどの文書構造をプログラムで操作する際に、既存の子ノードの前に新しいノードを挿入するために使用されます。例えば、ウェブページの特定の要素内に新しいテキストや別の要素を追加したり、並び順を変更したい場合に役立ちます。

このサンプルコードでは、まず新しいDom\Documentオブジェクトを作成し、ルート要素である<data>と、その子要素である<p>を追加しています。次に、<p>要素の中に「既存のテキストです。」というテキストノードを追加します。

ここで「ここに新しいテキストを挿入します。」という新しいテキストノードを作成し、親要素である$paragraphElement（<p>要素）のinsertBeforeメソッドを呼び出します。第一引数には挿入したい新しいノードを、第二引数にはその新しいノードを挿入する基準となる既存の子ノード（この例では「既存のテキストです。」のノード）を指定します。

この操作により、最終的な文書構造では「ここに新しいテキストを挿入します。既存のテキストです。」と、新しいテキストが既存のテキストの前に期待通りに挿入されます。

メソッドの第一引数$nodeは挿入する新しいノード自体を、第二引数$childは新しいノードを挿入する基準となる、既存の子ノードを指定します。$childがnullの場合、新しいノードは親ノードの末尾に追加されます。戻り値は挿入された新しいノードであり、これは引数で渡した$nodeと同じオブジェクトです。このメソッドを使うことで、文書の順序や内容を動的に変更できます。

Copy
1<?php
2
3/**
4 * Dom\Text::insertBefore メソッドの使用例。
5 *
6 * PHPのDOM拡張において、Dom\Text ノードは文字データのみを含み、子ノードを持つことはできません。
7 * insertBefore メソッドは Dom\Node から継承されていますが、
8 * Dom\Text インスタンスに対して子ノードを挿入しようとすると、
9 * DOM標準の「Hierarchy Request Error」が発生します。
10 * このサンプルコードは、その動作を捕捉し、なぜエラーが発生するのかを説明します。
11 */
12function demonstrateDomTextInsertBefore(): void
13{
14    $document = new Dom\Document();
15    $document->formatOutput = true; // 出力を整形します
16
17    // 1. 基本的なHTML構造を読み込みます
18    $document->loadHTML('<div><p>こんにちは、<span>世界！</span></p></div>');
19
20    // 2. 操作対象のDom\Text ノードを見つけます
21    // ここでは "<p>こんにちは、<span>世界！</span></p>" の中の "こんにちは、" テキストノードを探します
22    $paragraph = $document->getElementsByTagName('p')->item(0);
23    if (!$paragraph) {
24        echo "エラー: p要素が見つかりません。\n";
25        return;
26    }
27
28    $textNode = null;
29    foreach ($paragraph->childNodes as $childNode) {
30        if ($childNode instanceof Dom\Text && str_contains($childNode->nodeValue, 'こんにちは')) {
31            $textNode = $childNode;
32            break;
33        }
34    }
35
36    if (!$textNode) {
37        echo "エラー: 'こんにちは、' テキストノードが見つかりません。\n";
38        return;
39    }
40
41    echo "--- オリジナルHTML ---\n";
42    echo $document->saveHTML();
43    echo "\n";
44
45    // 3. 挿入を試みる新しい要素を作成します
46    $newElement = $document->createElement('b', '新しい太字テキスト');
47
48    echo "--- Dom\\Text::insertBefore を呼び出し中 ('{$textNode->nodeValue}' に) ---\n";
49
50    try {
51        // 4. Dom\Text インスタンスの insertBefore メソッドを呼び出します
52        // Dom\Text ノードは子ノードを持つことができないため、この操作は Hierarchy Request Error を引き起こします
53        $textNode->insertBefore($newElement);
54
55        // この行は通常実行されません
56        echo "予期せずノードが挿入されました。\n";
57        echo $document->saveHTML();
58    } catch (Dom\DomException $e) {
59        // 期待される Hierarchy Request Error を捕捉します
60        echo "期待されたエラーを捕捉しました: " . $e->getMessage() . "\n";
61        echo "理由: Dom\\Text ノードはDOMツリーにおいてリーフノードであり、子ノード（要素や他のテキストノードなど）を持つことはできません。\n";
62        echo "insertBefore メソッドは Dom\\Node から継承されていますが、Dom\\Text ノードの子を追加するのには適用できません。\n";
63        echo "\n--- 失敗後のHTML (変更なし) ---\n";
64        echo $document->saveHTML();
65    }
66}
67
68// 関数を実行して動作を確認します
69demonstrateDomTextInsertBefore();

PHPのDom\Text::insertBeforeメソッドは、DOMツリー内で、呼び出し元のノードの子ノードとして、新しいノードを既存の子ノードの前に挿入するために使われるメソッドです。引数$nodeには挿入したい新しいDom\Nodeオブジェクトを指定し、オプションの引数$childには、$nodeをその前に挿入したい既存の子ノードを指定します。$childを省略した場合、新しいノードは既存の子ノードの末尾に挿入されます。このメソッドは通常、挿入されたDom\Nodeを返します。

しかし、Dom\Textクラスのインスタンスは、HTMLやXMLドキュメント内の純粋なテキストデータのみを表現するノードであり、DOMツリーにおいて子ノードを持つことができません。そのため、Dom\Textノードに対してinsertBeforeメソッドを呼び出し、子ノードを挿入しようとすると、DOM標準で定められた「Hierarchy Request Error」というエラーが発生します。

提供されたサンプルコードは、この特定の挙動を明確に示しています。コードはまずHTMLドキュメントを作成し、その中から特定のテキストノード（Dom\Textインスタンス）を抽出します。その後、このテキストノードに対して新しい要素を挿入しようと試みますが、Dom\Textノードは子ノードを持てないため、期待通りDom\DomExceptionが捕捉され、「Hierarchy Request Error」が発生する様子が確認できます。このエラーは、Dom\Textノードが子要素を追加する対象ではないことを意味しています。