【PHP8.x】insertDataメソッドの使い方

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

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

基本的な使い方

insertDataメソッドは、DOMCharacterData型のノードに文字列データを挿入する処理を実行するメソッドです。DOMCharacterDataクラスは、XMLやHTMLドキュメント内で文字データを持つノード、例えばテキストノード（DOMText）、コメントノード（DOMComment）、CDATAセクションノード（DOMCDataSection）などが共通して持つ振る舞いを定義するための基底クラスです。

このinsertDataメソッドは、所属するDOMCharacterDataオブジェクトの現在の文字データに対し、指定された開始位置（オフセット）から、与えられた文字列を挿入します。オフセットは、文字データの先頭を0とする整数値で指定され、挿入された文字列によって元の文字データは指定位置から後方にずらされ、全体のデータ長が長くなります。

メソッドには二つの引数が必要です。最初の引数であるoffsetには、挿入を開始する位置を0以上の整数で指定します。二番目の引数であるdataには、ノードに挿入したい文字列データを指定します。このメソッドはデータを挿入するだけで、特に値を返しません。

例えば、既存のテキストコンテンツの中間に新しい単語を追加したい場合などに利用できます。ただし、指定されたoffsetがノードの現在のデータ長より大きい場合など、無効な位置を指定すると、DOMExceptionが発生する可能性があるため注意が必要です。PHPのDOM拡張機能を利用してドキュメントの構造や内容をプログラムで操作する際に重要な機能の一つです。

構文(syntax)


1<?php
2$characterDataNode = new DOMText("既存のテキスト");
3$characterDataNode->insertData(3, "挿入データ");
4?>

引数(parameters)

int $offset, string $data

int $offset: データの挿入を開始する位置を示す整数
string $data: 挿入する文字列

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

PHP DOMCharacterData::insertData() でテキスト挿入する


1<?php
2
3declare(strict_types=1);
4
5/**
6 * DOMCharacterData::insertData() を使用してテキストノードに文字列を挿入するサンプル
7 *
8 * この関数は、指定したテキストノードの特定の位置に新しい文字列を挿入する方法を示します。
9 */
10function demonstrateInsertData(): void
11{
12    // 1. DOMDocumentオブジェクトを生成します。
13    $dom = new DOMDocument('1.0', 'UTF-8');
14
15    // 2. 'Hello World!' というテキストを持つ <p> 要素を作成します。
16    $paragraph = $dom->createElement('p', 'Hello World!');
17    $dom->appendChild($paragraph);
18
19    // 3. <p> 要素内のテキストノード（DOMTextオブジェクト）を取得します。
20    // DOMTextはDOMCharacterDataを継承しているため、insertDataメソッドが使えます。
21    /** @var DOMText $textNode */
22    $textNode = $paragraph->firstChild;
23
24    echo '変更前: ' . $textNode->nodeValue . PHP_EOL;
25
26    // 4. insertData(offset, data) を呼び出します。
27    // offset: 文字列を挿入する位置（0から始まるインデックス）。
28    // data: 挿入する文字列。
29    // ここでは、5文字目 ('Hello'の後) に ' beautiful' を挿入します。
30    $offset = 5;
31    $data = ' beautiful';
32    $textNode->insertData($offset, $data);
33
34    // 5. 変更後のテキストノードの内容と、HTML全体を出力して確認します。
35    echo '変更後: ' . $textNode->nodeValue . PHP_EOL;
36    echo '---' . PHP_EOL;
37    echo '最終的なHTML出力:' . PHP_EOL;
38    echo $dom->saveHTML();
39}
40
41// 関数を実行します。
42demonstrateInsertData();
43
44?>

PHPのDOMCharacterData::insertDataメソッドは、DOM（Document Object Model）という仕組みを利用して、XMLやHTML文書のテキストデータ部分に新しい文字列を挿入するために使われます。このメソッドは、文字データを扱うDOMCharacterDataを継承しているノード、例えばDOMTextオブジェクトなどで使用されます。

このメソッドは二つの引数を取ります。一つ目の$offsetは整数型で、文字列を挿入する開始位置を0から始まるインデックスで指定します。二つ目の$dataは文字列型で、実際に挿入したいテキストの内容を指定します。このメソッド自体は戻り値を持ちませんが、対象のテキストノードの内容を直接変更します。

提供されたサンプルコードでは、最初にDOMDocumentオブジェクトを生成し、その中に「Hello World!」というテキストを含む<p>要素を作成して追加しています。次に、この<p>要素の内部にある「Hello World!」というテキストノード（DOMTextオブジェクト）を取得します。

そして、insertDataメソッドを使って、このテキストノードの5文字目の位置（「Hello」の直後）に「 beautiful」という文字列を挿入しています。この操作により、元の「Hello World!」というテキストは「Hello beautiful World!」に変化します。コードは変更前後のテキストノードの内容と、最終的なHTML構造全体を出力することで、挿入が正しく行われたことを確認しています。

DOMCharacterData::insertData()メソッドは、テキストノードなどの文字データを持つオブジェクトに対し、指定した位置に文字列を挿入します。引数$offsetは0から始まる文字位置を指定し、文字列の長さを超える値を指定した場合は、文字列の末尾に挿入されますので注意が必要です。このメソッドは元のノードの内容を直接変更（破壊的変更）します。戻り値は提供されないため、操作後のノードのnodeValueプロパティを確認して変更内容を取得してください。DOMDocumentオブジェクトのエンコーディング設定と挿入する文字列のエンコーディングが一致していることも、文字化けを防ぐ上で重要です。