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

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

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

基本的な使い方

prependメソッドは、Dom\ParentNodeに、指定されたノードまたは文字列をその子ノードリストの先頭に追加するメソッドです。Dom\ParentNodeは、DOMツリーにおいて子ノードを持つことができる要素を指します。

このメソッドを利用することで、対象となる親ノードの内部で、既存の子ノードがある場合はそれらのすべてよりも前に、指定された新しいコンテンツを挿入できます。もし親ノードに子ノードが一つも存在しない場合は、新しく追加されるノードが唯一の子として設定されます。

引数には、Dom\Node型のオブジェクト、または文字列を一つ以上指定することが可能です。文字列が渡された場合、それは自動的にテキストノードとして解釈され、挿入されます。

この機能は、HTMLやXMLドキュメントの構造を動的に操作する際に、特定の要素の開始位置に新しい要素やテキストコンテンツを効率的に追加したい場合に活用されます。例えば、ウェブページの特定のブロック要素の先頭に、新しい見出しや段落、あるいは警告メッセージなどを動的に挿入する際に役立ちます。

構文(syntax)


1$parentNode->prepend($nodesOrStrings);

引数(parameters)

Dom\Node|string ...$nodes

Dom\Node|string ...$nodes: 追加するDom\Nodeオブジェクトまたは文字列。複数指定可能

戻り値(return)

void

このメソッドは、指定したノードを対象のノードの最初の子ノードとして追加します。戻り値はありません。

サンプルコード

PHP: DOM要素の先頭にノードを追加する


1<?php
2
3/**
4 * HTML ドキュメントの要素の先頭に新しいノードまたは文字列を追加するサンプル関数。
5 *
6 * Dom\ParentNode::prepend メソッドの動作を示します。
7 * このメソッドは、指定された親ノードの最初の子として、一つ以上のノードまたは文字列を追加します。
8 * PHP 8 の DOM 拡張では、DOMElement クラスが Dom\ParentNode トレイトを使用しているため、
9 * このメソッドを利用できます。
10 *
11 * @return void
12 */
13function demonstrateDomPrepend(): void
14{
15    // 1. 新しい DOMDocument オブジェクトを作成します。
16    //    これはHTMLまたはXMLドキュメント全体を操作するための基盤となります。
17    $dom = new DOMDocument();
18
19    // 2. HTMLコンテンツをロードします。
20    //    この例では、IDが 'container' の div 要素を持つ単純なHTMLをロードします。
21    //    formatOutput を true に設定すると、後で出力されるHTMLが読みやすくなります。
22    $dom->loadHTML('<div id="container"><span>既存の要素</span></div>');
23    $dom->formatOutput = true;
24
25    echo "--- 元のHTML ---\n";
26    echo $dom->saveHTML();
27    echo "\n";
28
29    // 3. prepend メソッドを適用する親ノードをIDで取得します。
30    //    DOMElement クラスのインスタンスは Dom\ParentNode の機能を提供します。
31    $parentNode = $dom->getElementById('container');
32
33    // 4. 親ノードが正しく見つかった場合のみ、prepend 操作を実行します。
34    if ($parentNode instanceof DOMElement) {
35        // 5. 親ノードの先頭に追加する新しいノードや文字列を作成します。
36        //    新しい DOMElement オブジェクト（ここではパラグラフ）を作成して追加できます。
37        $newParagraph = $dom->createElement('p', 'これは先頭に追加される新しいパラグラフです。');
38
39        //    DOMText オブジェクトを作成して追加することもできます。
40        $newTextNode = $dom->createTextNode('これは追加されるテキストノードです。');
41
42        //    PHPの単なる文字列も直接追加できます。
43        $rawString = 'これは直接追加される文字列です。';
44
45        // 6. Dom\ParentNode::prepend メソッドを呼び出します。
46        //    引数として複数のノードや文字列を渡すことができます。
47        //    これらは指定された順序で親ノードの先頭に追加されます。
48        $parentNode->prepend($newParagraph, $newTextNode, $rawString);
49
50        echo "--- prepend後 のHTML ---\n";
51        echo $dom->saveHTML();
52        echo "\n";
53    } else {
54        echo "エラー: ID 'container' を持つ要素が見つかりませんでした。\n";
55    }
56}
57
58// サンプル関数を実行します。
59demonstrateDomPrepend();

PHP 8のDom\ParentNode::prependメソッドは、HTMLやXMLドキュメント内の既存の要素（親ノード）の先頭に、新しい子ノードや文字列を追加するために使用されます。このメソッドはDOMElementなど、Dom\ParentNodeトレイトを利用するDOM操作のクラスで利用可能です。

引数Dom\Node|string ...$nodesには、DOMNodeのインスタンス（例えばDOMElementやDOMText）またはPHPの通常の文字列を、複数指定して渡すことができます。これらの引数は、渡された順序で親ノードの最初の子として挿入されます。戻り値はvoidであり、このメソッドは何も値を返しません。

サンプルコードでは、まずIDが 'container' のdiv要素を含むHTMLコンテンツをロードします。次に、このdiv要素を親ノードとして取得し、新しいp要素、テキストノード、および直接の文字列を作成します。そして、prependメソッドを使ってこれら全てをdiv要素の先頭に一括で追加しています。これにより、既存のdiv要素の子要素の前に、新しい内容が指定した順序で挿入されたHTMLが生成されることを確認できます。

このprependメソッドは、HTMLなどのDOM要素の先頭に新しい子要素や文字列を追加するための機能です。PHPの配列の先頭に要素を追加する操作とは異なりますので混同しないよう注意してください。引数には、作成した新しいDOM要素やテキストノードのオブジェクトだけでなく、単なる文字列も直接渡すことができます。複数の引数を指定すると、それらは指定した順序で親要素の先頭に追加されます。このメソッドはvoidを返すため、処理の成功有無などは戻り値からは判断できません。対象の要素がDom\ParentNodeインターフェース（通常はDOMElementなど）の機能を持つオブジェクトであることを確認してから利用すると、予期せぬエラーを防ぎ、より安全にコードを記述できます。

PHP prepend to string で要素を先頭に追加する


1<?php
2
3// DOMDocumentを作成し、HTMLコンテンツを扱います。
4$dom = new DOMDocument('1.0', 'UTF-8');
5$dom->formatOutput = true; // 出力されるHTMLを整形して見やすくします。
6
7// 既存のHTMLコンテンツをロードします。
8// <body>要素はDom\ParentNodeを継承しており、prependメソッドを使用できます。
9$dom->loadHTML('<body><p>これは既存の段落です。</p></body>');
10
11// ドキュメントから<body>要素を取得します。
12$body = $dom->getElementsByTagName('body')->item(0);
13
14// Dom\ParentNode::prepend メソッドを使用して、<body>要素の先頭に文字列を追加します。
15// 引数に文字列を渡すと、それは自動的にテキストノードとして扱われ、追加されます。
16// 追加される順序は、後からprependされたものがより先頭に来ます。
17if ($body instanceof Dom\ParentNode) {
18    $body->prepend('これは一番最初にprependされたテキストです。');
19}
20
21// 次に、Dom\Nodeを新しく作成し、それもprependで先頭に追加します。
22// prependメソッドはDOMノードと文字列の両方を引数として受け入れます。
23$heading = $dom->createElement('h1', '新しく追加された見出し');
24if ($body instanceof Dom\ParentNode) {
25    $body->prepend($heading);
26}
27
28// 変更されたHTMLを文字列として出力します。
29// prependされた要素や文字列が、元のコンテンツの前に挿入されていることを確認できます。
30echo $dom->saveHTML();
31
32?>

PHP 8で提供されるDom\ParentNode::prependメソッドは、HTMLやXMLドキュメントの構造を操作する際に使用する便利な機能です。このメソッドはDom\ParentNodeクラスに属しており、<body>や<div>といった子ノードを持てる要素（親ノード）の先頭に、新しいコンテンツを追加できます。

引数には、追加したいDom\Nodeオブジェクト（例：<h1>タグ）や、テキストとして扱いたい文字列を複数指定できます。文字列を渡すと、メソッドはそれを自動的にテキストノードとして変換し、追加します。メソッドが実行されると、指定されたノードまたはテキストは、親ノードの既存のすべての子ノードよりも先頭に挿入されます。特に、複数の要素や文字列を繰り返しprependした場合、後から追加されたものが、それ以前に追加されたものよりもさらに一番の先頭に配置されるという挙動をします。このメソッドは処理結果として特に値を返さないため、戻り値はvoidです。既存のHTMLコンテンツの先頭に、新しい見出しや段落などを動的に挿入したい場合に非常に有効です。

Dom\ParentNode::prependメソッドは、HTMLやXMLドキュメントのDOM構造において、指定した要素の「子ノードの先頭」に新しいコンテンツを追加する機能です。これは一般的なPHPの文字列操作関数とは異なり、DOMツリーの構造を変更するために使用されます。

引数には、新しく作成したDom\Nodeオブジェクト、または純粋な文字列を渡すことができます。文字列を渡した場合、それは自動的にテキストノードとしてDOMツリーに挿入されます。このため、HTMLタグを含む文字列を直接渡しても、タグがエスケープされ、テキストとして表示される点にご注意ください。HTML要素として追加したい場合は、Dom\createElementなどでノードを作成し、それを引数として渡す必要があります。

複数のコンテンツをprependで追加する際は、後から追加されたものがより先頭に配置されます。このメソッドは何も値を返さない（void）ため、メソッドチェーンはできません。対象の要素がDom\ParentNode型であることを確認してから利用してください。