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

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

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

基本的な使い方

insertAdjacentTextメソッドは、DOMElementクラスに属するメソッドで、HTMLやXMLドキュメント内の特定のDOM要素に対して、指定された位置にテキストコンテンツを挿入するメソッドです。このメソッドは、既存の要素の構造を直接変更することなく、その要素の周辺や内部に新しいテキストノードを効率的に追加したい場合に利用されます。

テキストを挿入する位置は、メソッドの第一引数で指定します。利用可能なキーワードは以下の四つです。'beforebegin' は、対象要素の開始タグの直前、つまりその要素の外側にテキストを挿入します。'afterbegin' は、対象要素の開始タグの直後、その要素の最初の子としてテキストを挿入します。'beforeend' は、対象要素の終了タグの直前、その要素の最後の子としてテキストを挿入します。'afterend' は、対象要素の終了タグの直後、その要素の外側にテキストを挿入します。

第二引数には挿入するテキスト文字列を渡します。このメソッドの重要な特徴は、挿入される内容が常に純粋なテキストとして扱われる点です。これにより、挿入文字列にHTMLタグなどが含まれていても、それらは自動的にエスケープされて追加されます。結果として、意図しないHTML構造の変更や、クロスサイトスクリプティング（XSS）のようなセキュリティリスクを効果的に防ぎ、安全かつ簡潔なDOM操作を可能にします。

構文(syntax)


1<?php
2
3$domElement->insertAdjacentText('beforeend', '挿入するテキスト');

引数(parameters)

string $where, string $data

string $where: テキストを挿入する位置を指定する文字列。以下のいずれかの値を取ります。
- "beforebegin": 要素の直前に挿入します。
- "afterbegin": 要素の直後に挿入します。
- "beforeend": 要素の末尾に挿入します。
- "afterend": 要素の直後に挿入します。
string $data: 挿入するテキストを指定する文字列。

戻り値(return)

void

指定された位置にテキストノードを挿入します。戻り値はありません。

サンプルコード

PHP DOMElement::insertAdjacentTextでテキスト挿入する


1<?php
2
3/**
4 * DOMElement::insertAdjacentText メソッドの利用例を示します。
5 * このメソッドは、指定された要素の特定の相対位置にテキストを挿入する際に便利です。
6 * 特に、既存の要素の内側（最初や最後）や外側（直前や直後）に
7 * テキストノードを「正確に」挿入したい場合に有効で、
8 * 「PHPでDOMにテキストを思い通りにinsertできない」という課題解決に役立ちます。
9 */
10function demonstrateInsertAdjacentText(): void
11{
12    // 1. DOMDocument オブジェクトを生成し、基本的なHTML構造を設定します。
13    //    formatOutput を true に設定すると、出力されるHTMLが見やすくなります。
14    $dom = new DOMDocument('1.0', 'UTF-8');
15    $dom->formatOutput = true;
16
17    // 2. ルート要素 (例として <body>) を作成し、DOMに追加します。
18    $body = $dom->createElement('body');
19    $dom->appendChild($body);
20
21    // 3. 挿入操作のターゲットとなる <p> 要素を作成し、初期テキストを設定します。
22    $targetElement = $dom->createElement('p');
23    $targetElement->textContent = 'ターゲット要素の既存テキスト';
24    $body->appendChild($targetElement);
25
26    // --- insertAdjacentText 実行前のDOM構造を出力 ---
27    echo "--- 1. insertAdjacentText 実行前のDOM構造 ---\n";
28    echo $dom->saveHTML() . "\n\n";
29
30    // 4. insertAdjacentText を使って、様々な位置にテキストを挿入します。
31    //    $where 引数で挿入位置を指定し、$data 引数で挿入するテキストを指定します。
32
33    // 'beforebegin': ターゲット要素の開始タグの直前にテキストを挿入します。
34    //                これはターゲット要素の「外側」に、兄弟ノードとして挿入されます。
35    $targetElement->insertAdjacentText('beforebegin', '《beforebegin: ターゲット要素の直前》');
36
37    // 'afterbegin': ターゲット要素の開始タグの直後にテキストを挿入します。
38    //               これはターゲット要素の「内側」の、最初の子ノードとして挿入されます。
39    $targetElement->insertAdjacentText('afterbegin', '《afterbegin: ターゲット要素の内部開始》');
40
41    // 'beforeend': ターゲット要素の終了タグの直前にテキストを挿入します。
42    //              これはターゲット要素の「内側」の、最後の子ノードとして挿入されます。
43    $targetElement->insertAdjacentText('beforeend', '《beforeend: ターゲット要素の内部終了》');
44
45    // 'afterend': ターゲット要素の終了タグの直後にテキストを挿入します。
46    //             これはターゲット要素の「外側」に、兄弟ノードとして挿入されます。
47    $targetElement->insertAdjacentText('afterend', '《afterend: ターゲット要素の直後》');
48
49    // --- insertAdjacentText 実行後のDOM構造を出力 ---
50    echo "--- 2. insertAdjacentText 実行後のDOM構造 ---\n";
51    echo $dom->saveHTML() . "\n";
52}
53
54// 関数を実行して、デモンストレーションを開始します。
55demonstrateInsertAdjacentText();
56
57?>

PHP 8のDOMElement::insertAdjacentTextメソッドは、DOM要素の指定された相対位置にテキストノードを効率的に挿入するための機能です。このメソッドは、既存のHTML要素の内部または外部に、テキストコンテンツを正確に配置したい場合に非常に役立ち、「PHPでDOMにテキストを思い通りに挿入できない」といった課題を解決します。

引数$whereには、テキストを挿入する相対位置を文字列で指定します。これには'beforebegin'（ターゲット要素の開始タグ直前、要素の外側）、'afterbegin'（ターゲット要素の開始タグ直後、要素の内側の最初）、'beforeend'（ターゲット要素の終了タグ直前、要素の内側の最後）、'afterend'（ターゲット要素の終了タグ直後、要素の外側）の4つの選択肢があります。$data引数には、実際にDOMに挿入するテキストコンテンツを指定します。このメソッドはvoidを返すため、実行後に値を返すことはありません。

サンプルコードでは、まずDOMDocumentオブジェクトを作成し、<body>要素内にターゲットとなる<p>要素を用意します。そして、insertAdjacentTextメソッドを各$where値で順に実行することで、挿入位置がどのように変化するかを示しています。例えば、'beforebegin'では<p>要素の直前にテキストが追加され、'afterbegin'では<p>要素の開始タグのすぐ内側にテキストが挿入される様子が確認できます。これにより、各オプションがDOM構造に与える影響が具体的に理解できます。

このメソッドは、指定したDOM要素の特定の相対位置にテキストノードを挿入する際に利用します。既存のtextContentを上書きするのではなく、新しいテキストを「追加」する点に注意が必要です。第一引数$whereは挿入位置を厳密に指定するキーワードであり、その種類によって要素の内側か外側か、最初か最後かが決まります。特に'beforebegin'と'afterend'はターゲット要素の「外側」に、'afterbegin'と'beforeend'は「内側」にテキストが挿入されることを理解しておくことが重要です。戻り値はvoidであるため、メソッド実行後はsaveHTML()などでDOM構造を確認し、意図通りにテキストが挿入されたか検証することが安全な利用に繋がります。これにより、DOMへのテキスト挿入に関する一般的な課題を解決し、HTML構造を細かく制御できるようになります。

PHP DOMElement::insertAdjacentText で要素の直前にテキスト挿入する


1<?php
2
3/**
4 * DOMElement::insertAdjacentText メソッドのサンプル
5 * 指定された要素の特定の場所にテキストノードを挿入します。
6 * キーワード「insertbefore」に関連して、既存の要素の直前にテキストを挿入する例を示します。
7 */
8
9// DOMDocument オブジェクトを作成し、HTML5 に対応させる
10$dom = new DOMDocument('1.0', 'UTF-8');
11$dom->formatOutput = true; // 出力時に整形を有効にする
12
13// ルート要素となる <div> を作成
14$rootDiv = $dom->createElement('div');
15$dom->appendChild($rootDiv);
16
17// 挿入対象となる <p> 要素を作成し、テキストノードを追加
18$paragraphElement = $dom->createElement('p', 'これは元の段落のテキストです。');
19$rootDiv->appendChild($paragraphElement);
20
21// DOMElement::insertAdjacentText を使用して、<p> 要素の直前 ('beforebegin') にテキストを挿入
22// 'beforebegin' は、要素の開始タグの直前（兄弟要素として）にテキストを挿入します。
23$paragraphElement->insertAdjacentText('beforebegin', 'このテキストは段落の直前に挿入されました。 ');
24
25// 最終的な HTML を出力して確認
26echo $dom->saveHTML();
27
28/*
29期待される出力例:
30<div>
31  このテキストは段落の直前に挿入されました。 <p>これは元の段落のテキストです。</p>
32</div>
33*/
34
35?>

PHP 8のDOMElement::insertAdjacentTextメソッドは、指定されたHTML要素の特定の場所に新しいテキストノードを挿入する際に使用されます。このメソッドは、既存の要素を変更せずに、その周辺にテキストを追加したい場合に便利です。

引数は二つあります。一つ目の$whereには、テキストを挿入する位置を文字列で指定します。「beforebegin」（要素の開始タグの直前、兄弟要素として）、「afterbegin」（要素の開始タグの直後、最初の子要素として）、「beforeend」（要素の終了タグの直前、最後の子要素として）、「afterend」（要素の終了タグの直後、兄弟要素として）などの値が利用可能です。二つ目の$dataには、挿入したいテキストの内容を文字列で指定します。このメソッドは要素にテキストを挿入する操作を行うだけで、特定の値を返さないため、戻り値はvoidとなります。

サンプルコードでは、まずDOMDocumentを使ってHTML文書の構造を準備し、ルートとなる<div>要素と、その中にテキストを持つ<p>要素を作成しています。そして、$paragraphElement->insertAdjacentText('beforebegin', '...')を呼び出すことで、<p>要素の開始タグの直前、つまり<div>の子要素として<p>の兄弟位置に新しいテキストを挿入しています。これは、キーワード「insertbefore」が示すような、既存の要素の直前にコンテンツを追加する操作を実現しています。結果として、<div>の中に「このテキストは段落の直前に挿入されました。」というテキストが先に出力され、その後に<p>要素が続く形となります。

DOMElement::insertAdjacentTextは、指定要素の周りに純粋なテキストノードを挿入するメソッドです。引数 $data にHTMLタグを含めても、それらはHTML要素としてではなく、単なる文字列として扱われます。もしHTML要素自体を挿入したい場合は、insertAdjacentElementなど別のDOM操作メソッドをご利用ください。

$where引数には、'beforebegin', 'afterbegin', 'beforeend', 'afterend'のいずれかを正確に指定する必要があります。サンプルコードの'beforebegin'は、指定要素の直前にテキストを兄弟ノードとして挿入します。これは「insertbefore」のように既存要素の前にテキストを追加する場面で特に役立ちます。$whereの指定ミスは、意図しない位置への挿入やエラーの原因となるため、各位置の意味を理解し、慎重に指定してください。