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

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

作成日: 2025年09月11日更新日: 2025年11月24日

基本的な使い方

insertBeforeメソッドは、PHPのDOM拡張機能において、テキストノードを表すDOMTextクラスに定義されており、HTMLやXMLドキュメントのツリー構造を操作する際に、新しいノードを既存の子ノードのリストにおける特定の参照ノードの直前に挿入する機能を提供するメソッドです。

このメソッドはDOMTextクラスが継承しているDOMNodeクラスの共通機能として提供されています。基本的な構文はinsertBefore(DOMNode $new_node, ?DOMNode $ref_node = null)です。$new_nodeには、挿入したい新しいノードオブジェクト（例：DOMElementや別のDOMTextなど）を指定します。$ref_nodeには、$new_nodeをその直前に挿入したい既存の子ノードを指定します。PHP 8からは$ref_nodeを省略できるようになり、省略された場合は$new_nodeが子ノードリストの末尾に追加される動作となります。メソッドは最終的に挿入された$new_nodeオブジェクトを返します。

しかし、DOMTextクラスのインスタンスはテキストノードであり、DOMの仕様上、子ノードを持つことができません。そのため、DOMTextインスタンス自身に対してこのinsertBeforeメソッドを呼び出し、新しいノードを子として追加しようとすると、DOMの規則に反する操作となり、DOMExceptionのHierarchyRequestErrorというエラーが発生します。したがって、このメソッドは通常、DOMElementのような子ノードを持つことができる要素ノードに対して利用されることがほとんどです。

構文(syntax)


1$domText->insertBefore($newChild, $refChild);

引数(parameters)

DOMNode $node, ?DOMNode $child = null

DOMNode $node: 挿入するノードを指定します。
?DOMNode $child = null: $node を挿入する前に、指定された $child を削除します。省略された場合は、$node は現在位置に挿入されます。

戻り値(return)

DOMNode

DOMText オブジェクトが挿入された位置を示す DOMNode オブジェクトを返します。

サンプルコード

PHP DOMDocument insertBeforeで要素を挿入する


1<?php
2
3/**
4 * DOMTextノードの前に新しい要素を挿入するサンプルコードです。
5 * DOMTextはDOMNodeを継承しておりinsertBeforeメソッドを持ちますが、
6 * テキストノード自体は子ノードを持てません。
7 * そのため、通常はDOMTextの親ノードに対してinsertBeforeを呼び出し、
8 * DOMTextノードを挿入位置の基準（第2引数）として指定します。
9 */
10function insertNodeBeforeDOMText(): void
11{
12    // 新しいDOMDocumentを作成
13    $dom = new DOMDocument('1.0', 'UTF-8');
14    // 出力を見やすくするために整形を有効にします
15    $dom->formatOutput = true;
16    // 空白ノードを無視しない設定 (デフォルトですが明示)
17    $dom->preserveWhiteSpace = false;
18
19    // ルート要素 <body> を作成し、DOMに添付
20    $body = $dom->createElement('body');
21    $dom->appendChild($body);
22
23    // 既存のテキストノードを作成し、<body>要素に添付します
24    // このテキストノードが、新しいノードを挿入する際の基準になります
25    $existingTextNode = $dom->createTextNode('既存のテキストコンテンツ');
26    $body->appendChild($existingTextNode);
27
28    // 変更前のHTML構造を出力
29    echo "--- 変更前 ---\n";
30    echo $dom->saveHTML() . "\n\n";
31
32    // 挿入する新しい要素 <p> を作成
33    $newParagraph = $dom->createElement('p', 'ここに新しい段落を挿入');
34
35    // <body>要素の子として、$existingTextNode の前に $newParagraph を挿入します。
36    // insertBeforeメソッドは挿入されたノードを返します。
37    $insertedNode = $body->insertBefore($newParagraph, $existingTextNode);
38
39    // 変更後のHTML構造を出力
40    echo "--- 変更後 ---\n";
41    echo $dom->saveHTML() . "\n";
42
43    // 挿入されたノードがDOMNodeのインスタンスであることを確認
44    echo "\n挿入されたノードのタイプ: " . get_class($insertedNode) . "\n";
45    echo "挿入されたノードのタグ名: " . $insertedNode->tagName . "\n";
46}
47
48// 関数を実行
49insertNodeBeforeDOMText();

PHP 8のDOMText::insertBeforeメソッドは、DOMNodeを継承しているため存在しますが、テキストノード自体は子ノードを持てません。このため、DOMTextノードから直接このメソッドを呼び出すことは一般的ではありません。通常は、DOMTextノードの親ノードに対してinsertBeforeメソッドを呼び出し、第2引数にDOMTextノードを指定することで、そのテキストノードの前に新しいノードを挿入します。

このメソッドは、指定されたノードを既存の子ノードの前に挿入するために使用されます。第1引数 $node には、挿入したい新しいDOMNodeオブジェクトを指定します。第2引数 $child には、新しいノードを挿入したい位置の基準となる既存のDOMNodeオブジェクトを指定します。この$childノードの直前に$nodeが挿入されます。$childを省略またはnullにした場合、$nodeは子ノードリストの末尾に追加されます。メソッドは、挿入された新しいDOMNodeオブジェクトを返します。

サンプルコードでは、まず新しいDOMDocumentを作成し、<body>要素とその中に既存のテキストコンテンツというDOMTextノードを追加します。次に、挿入したい<p>要素を作成します。そして、<body>要素（DOMTextノードの親）に対してinsertBeforeメソッドを呼び出し、第1引数に作成した<p>要素を、第2引数に既存のテキストコンテンツのDOMTextノードを指定しています。これにより、既存のテキストノードの直前に新しい段落が挿入され、変更前後のHTML出力でその変化を確認できます。戻り値として、挿入された<p>要素のDOMNodeオブジェクトが得られます。

DOMTextノードは子ノードを持てないため、insertBefore メソッドはDOMTextノードの「親ノード」に対して呼び出すのが一般的な使い方です。この際、第2引数に挿入位置の基準となるDOMTextノードを指定し、その手前に新しいノードを挿入します。第2引数が null の場合は、新しいノードが親ノードの末尾に追加されます。メソッドは挿入されたノード自身を返します。DOMDocument の formatOutput を true に設定すると、出力されるHTMLが整形され、確認しやすくなります。