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

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

作成日: 2025年09月11日更新日: 2026年02月11日

基本的な使い方

prependメソッドは、DOMParentNodeクラスに属し、指定されたノードやテキストコンテンツを、その親ノードの最初の子として追加するメソッドです。このメソッドは、引数として複数のDOMNodeオブジェクトまたは文字列を受け取ることができ、それらを指定された順序で、既存の子ノードの前に挿入します。

具体的には、もし引数としてDOMNodeオブジェクトが渡された場合、そのノードは親ノードの最初の子として挿入されます。この際、もし挿入されるノードが既にDOMツリー上の別の場所に存在していた場合、元の位置から移動されて、新しい親ノードの先頭に配置されます。一方、引数として文字列が渡された場合は、その文字列がテキストノードとして自動的に作成され、同様に親ノードの最初の子として挿入されます。

この機能は、HTMLやXMLドキュメントを動的に操作する際に非常に便利です。例えば、特定の要素の先頭に新しい情報ブロックを追加したい場合や、既存のコンテンツの前に注意書きやヘッダー情報を挿入したい場合などに活用できます。このメソッドは戻り値を持たず（void）、DOMツリー構造を変更する操作であるため、既存の子ノードの順序に影響を与えることに注意が必要です。このメソッドを使用することで、ドキュメントの構造を柔軟かつ効率的に操作できます。

構文(syntax)


1<?php
2
3// DOMElement は DOMParentNode インターフェースを実装しています
4$parentNode = new DOMElement('div');
5
6// 追加するノードまたはテキストコンテンツを準備します
7$newElement = new DOMElement('span', '新しい先頭要素');
8$newText = '新しい先頭テキスト';
9
10// DOMParentNode::prepend メソッドを呼び出して、
11// 指定された複数のノードまたはテキストを親ノードの先頭に追加します。
12$parentNode->prepend($newElement, $newText);
13
14?>

引数(parameters)

DOMNode|string ...$nodes

DOMNode|string ...$nodes: 追加するノードまたはHTML文字列。複数のノードや文字列をカンマ区切りで指定できます。

戻り値(return)

void

このメソッドは、指定されたノードを現在のノードの最初の子供として挿入します。操作はDOMツリーに対して行われ、このメソッド自体は何も返しません。

サンプルコード

PHP DOM::prependで子要素を先頭に追加する


1<?php
2
3/**
4 * DOMParentNode::prepend メソッドの使用例を示します。
5 * このメソッドは、指定されたノードまたは文字列を
6 * 現在のノードの子のリストの先頭に追加します。
7 *
8 * この機能は、HTMLやXMLのようなDOMツリー構造の要素の先頭に
9 * 新しい子要素やテキストを追加する際に使用します。
10 * PHPの配列操作 (例: array_unshift() ) とは異なる点に注意してください。
11 */
12function demonstrateDomPrepend(): void
13{
14    // 1. DOMDocument オブジェクトを作成します。
15    //    これはHTML/XMLドキュメントを表現するための基盤となります。
16    $dom = new DOMDocument('1.0', 'UTF-8');
17    $dom->formatOutput = true; // 出力を整形して見やすくします
18
19    // 2. HTMLの基本的な構造として、<body>要素を作成し、ドキュメントに追加します。
20    $body = $dom->createElement('body');
21    $dom->appendChild($body);
22
23    // 3. 親となる<div>要素を作成し、<body>要素の子として追加します。
24    $parentDiv = $dom->createElement('div');
25    $body->appendChild($parentDiv);
26
27    // 4. 既存の子要素をいくつか作成し、親<div>要素に追加します。
28    $p1 = $dom->createElement('p', '既存の段落1');
29    $parentDiv->appendChild($p1);
30
31    $p2 = $dom->createElement('p', '既存の段落2');
32    $parentDiv->appendChild($p2);
33
34    echo "--- 最初の状態 ---\n";
35    echo $dom->saveHTML() . "\n\n";
36
37    // 5. DOMParentNode::prepend を使って、新しい要素を親<div>要素の先頭に追加します。
38    //    DOMParentNode は、DOMElement (例: $parentDiv) などのクラスが実装するインターフェース/トレイトです。
39    //    そのため、$parentDiv に対して prepend を呼び出すことができます。
40    $pNewFirst = $dom->createElement('p', '◆先頭に追加された新しい段落 (単一ノード)');
41    $parentDiv->prepend($pNewFirst);
42
43    echo "--- 単一要素を追加後 ---\n";
44    echo $dom->saveHTML() . "\n\n";
45
46    // 6. 複数のノードや文字列を一度に先頭に追加することも可能です。
47    //    prepend メソッドの引数は可変長引数 (...$nodes) なので、
48    //    複数の DOMNode オブジェクトや文字列をコンマ区切りで渡せます。
49    $textNode = $dom->createTextNode('◆これは先頭に追加されたテキストノードです。');
50    $pAnother = $dom->createElement('p', '◆さらに先頭に追加された段落 (複数ノードの例)');
51    $parentDiv->prepend($textNode, $pAnother);
52
53    echo "--- 複数要素とテキストノードを追加後 ---\n";
54    echo $dom->saveHTML();
55}
56
57// 関数を実行して、DOM操作の結果を確認します。
58demonstrateDomPrepend();

PHP 8のDOMParentNode::prependメソッドは、HTMLやXMLなどのドキュメントオブジェクトモデル（DOM）ツリー構造において、親となるノードの子ノードリストの先頭に、新しいノードやテキストコンテンツを追加するための機能です。このメソッドは、DOMElementのようにDOMParentNodeインターフェースを実装するすべてのオブジェクトで使用できます。

引数には、追加したいDOMNodeオブジェクト、または単純な文字列を、一つあるいは複数（コンマで区切って）指定することが可能です。これにより、既存の要素の先頭に、新しいHTML要素やプレーンテキストを柔軟に挿入できます。例えば、サンプルコードでは、既存のdiv要素の先頭に新しい<p>要素を追加したり、さらにテキストノードと別の<p>要素をまとめて追加したりする様子が示されています。

このメソッドの戻り値はvoidです。これは、操作が成功したかどうかの情報などを直接返すのではなく、呼び出し元のDOMツリーが内部的に変更されることを意味します。PHPの配列を操作するarray_unshift()のように、配列の先頭に要素を追加する機能とは異なり、DOMParentNode::prependはDOMツリー構造専用の操作です。ウェブコンテンツの動的な生成や編集で、特定の要素の先頭に新しいコンテンツを効率的に挿入したい場合に役立ちます。

DOMParentNode::prependメソッドは、HTMLやXMLなどのDOMツリー構造において、指定した親ノードの子リストの先頭に新しい子ノードやテキストを追加する際に使用します。このメソッドは、PHPの配列を操作するarray_unshift()とは全く異なる機能ですので、混同しないよう特に注意してください。DOMElementなど、DOMParentNodeインターフェースを実装したオブジェクトに対して呼び出すことができます。引数にはDOMNodeオブジェクトまたは文字列を一つ、あるいは複数指定でき、それらが指定された順序で親ノードの先頭に挿入されます。戻り値はvoid（何も返さない）です。DOM操作中に要素が見つからないなどの問題が発生した場合は例外をスローすることがあるため、コードの堅牢性を高めるには適切なエラーハンドリングも検討することをお勧めします。

PHP DOMParentNode::prepend で先頭に文字列を追加する


1<?php
2
3/**
4 * DOMParentNode::prepend メソッドのサンプルコード
5 * DOM要素の先頭に文字列コンテンツを追加する方法を示します。
6 * これは「既存のコンテンツの先頭に文字列を追加する」という操作を、DOMの文脈で実現するものです。
7 */
8
9// DOMDocumentのインスタンスを作成
10// HTMLのルートノードとして機能し、DOMツリー全体を管理します。
11$dom = new DOMDocument('1.0', 'UTF-8');
12$dom->formatOutput = true; // 生成されるHTMLを整形して読みやすくします。
13
14// HTML構造の構築
15// <body>要素とその中にidが 'target-div' の<div>要素を作成します。
16$body = $dom->createElement('body');
17$div = $dom->createElement('div', '既存のコンテンツ');
18$div->setAttribute('id', 'target-div');
19$body->appendChild($div);
20$dom->appendChild($body); // DOMツリーにbody要素を追加します。
21
22// ターゲットとなるDOMElementを取得
23// prependメソッドはDOMParentNodeインターフェースを実装するクラス（例: DOMElement）で利用できます。
24$targetDiv = $dom->getElementById('target-div');
25
26if ($targetDiv) {
27    // DOMParentNode::prepend を使用して、指定した要素の子ノードの先頭に文字列を追加します。
28    // この操作は、要素の内部コンテンツの先頭に新しいテキストを挿入することに相当します。
29    $targetDiv->prepend('追加された新しいコンテンツ: ');
30
31    // 最終的なHTML構造を出力
32    // `saveHTML()` メソッドは、現在のDOMツリーをHTML文字列として返します。
33    echo $dom->saveHTML();
34} else {
35    // ターゲット要素が見つからなかった場合のメッセージ
36    echo "ターゲットとなる 'target-div' 要素が見つかりませんでした。\n";
37}

DOMParentNode::prependメソッドは、PHPでHTMLやXMLドキュメントを操作する際に、指定したDOM要素の先頭に新しいコンテンツ（文字列や他のDOMノード）を追加するために使用されます。このサンプルコードは、既存のHTML要素の内部に、後から文字列コンテンツを挿入する方法を示しています。

まず、DOMDocumentのインスタンスを作成し、基本的なHTML構造としてbody要素とその中にidがtarget-divのdiv要素を構築しています。このdiv要素には「既存のコンテンツ」という初期テキストが含まれています。

次に、getElementByIdメソッドを使って、このtarget-div要素を取得します。取得したDOMElementオブジェクトはDOMParentNodeインターフェースを実装しているため、prependメソッドを利用できます。$targetDiv->prepend('追加された新しいコンテンツ: ');という行では、「追加された新しいコンテンツ: 」という文字列を引数として渡しており、これによりtarget-div要素の内部コンテンツの先頭にこの文字列が挿入されます。

prependメソッドは、DOMNodeオブジェクトまたは文字列を可変長引数として受け取ります。これにより、複数のノードや文字列を一度に要素の先頭に追加することが可能です。メソッドは直接DOMツリーを変更するため、戻り値はvoid（何も返さない）です。

最終的にsaveHTML()メソッドで現在のDOMツリーをHTML文字列として出力すると、元の「既存のコンテンツ」の前に「追加された新しいコンテンツ: 」が付加された完全なHTMLが表示されます。これは、動的にウェブページの内容を更新する際などに、既存のコンテンツの先頭に新しい情報を追加したい場合に役立つ機能です。

DOMParentNode::prependメソッドは、指定したDOM要素の内部コンテンツの先頭に、新しいコンテンツを追加する際に使用します。引数にはDOMNodeオブジェクトまたは文字列を一つ、あるいは複数指定できます。

特に文字列を引数に渡した場合、それはHTMLタグとしてではなく、単なるテキストコンテンツとして扱われる点にご注意ください。もし、<div>などのHTML要素を先頭に追加したい場合は、DOMDocument::createElement()などでDOMElementオブジェクトを作成し、それをprependの引数として渡す必要があります。

このメソッドはDOMツリー内のデータを操作するものであり、メソッド自体は何も値を返しません（void）。最終的なHTMLとして表示するには、DOMDocument::saveHTML()のようなメソッドで出力する作業が必要です。

サンプルコードのように、ターゲットとなる要素が確実に存在するかをif文で確認してからメソッドを呼び出すことで、より安全に利用できます。