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

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

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

基本的な使い方

prependメソッドは、DOMDocumentオブジェクトに新しい子ノードを先頭に追加するメソッドです。このメソッドは、XMLやHTMLドキュメントの構造をプログラムで操作する際に利用され、既存の子ノードリストの一番最初に、指定したノードを挿入したい場合に特に役立ちます。

具体的には、DOMDocumentオブジェクトが持つ子ノードの集合に対して、引数として渡されたDOMNodeオブジェクトを最初の位置に配置します。これにより、ドキュメントのツリー構造の順番を効率的に変更することが可能です。

このメソッドはPHP 8で導入されました。それ以前のバージョンでは、同様の操作を行うためにDOMDocument::insertBeforeメソッドとfirstChildプロパティを組み合わせて使用する必要がありましたが、prependメソッドの登場により、より直感的かつ簡潔な記述で同じ処理を実現できるようになりました。これにより、コードの可読性が向上し、ドキュメント操作の記述が容易になります。

例えば、HTMLドキュメントの<head>要素の先頭に特定の<meta>タグを追加したり、XMLドキュメントのルート要素の直下にコメントノードを挿入したりするような場面で活用できます。メソッドが成功した場合、追加されたDOMNodeオブジェクト自身が返され、失敗した場合はfalseが返されます。

構文(syntax)


1<?php
2$dom = new DOMDocument('1.0', 'UTF-8');
3$newElement = $dom->createElement('example');
4$dom->prepend('ドキュメント冒頭のテキスト', $newElement, '<!-- ドキュメント冒頭のコメント -->');
5?>

引数(parameters)

DOMNode|string ...$nodes

DOMNode|string ...$nodes: 要素の先頭に追加する、1つ以上のDOMNodeオブジェクトまたはXML/HTML文字列

戻り値(return)

void

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

サンプルコード

PHP DOMDocument::prependでノードを先頭に追加する


1<?php
2
3// DOMDocument::prepend メソッドのサンプルコード
4// PHP 8.3以降で利用可能です。
5// DOMNodeを継承したクラス（DOMDocumentを含む）のインスタンスの子ノードリストの先頭に、
6// 新しいノード（DOMNodeオブジェクトまたは文字列）を追加します。
7
8// 1. DOMDocumentオブジェクトを生成します。
9//    HTML文書として扱うため、use HTML5 を有効にします。（PHP 8.4以降のDOMDocumentはHTML5モードがデフォルトになります）
10$dom = new DOMDocument('1.0', 'UTF-8');
11$dom->formatOutput = true; // 出力時に整形を行うように設定
12
13// 2. ドキュメントのルート要素（例: <html>）を作成し、DOMDocumentに追加します。
14$htmlElement = $dom->createElement('html');
15$dom->appendChild($htmlElement);
16
17// 3. ルート要素の中にボディ要素を作成し、追加します。
18$bodyElement = $dom->createElement('body');
19$htmlElement->appendChild($bodyElement);
20
21// 4. ボディ要素の中にパラグラフ要素を作成し、追加します。
22$paragraphElement = $dom->createElement('p', 'これは既存のパラグラフです。');
23$bodyElement->appendChild($paragraphElement);
24
25echo "--- prepend実行前のDOM構造 ---" . PHP_EOL;
26echo $dom->saveHTML() . PHP_EOL;
27
28// 5. DOMDocumentインスタンスの直接の子ノードリストの先頭に新しいコメントノードを追加します。
29//    DOMDocumentの子ノードは通常、XML宣言の後のドキュメント要素（例: <html>）一つです。
30//    したがって、このコメントは <html> タグの前に挿入されます。
31$newComment = $dom->createComment('これはprependで追加されたコメントです。');
32$dom->prepend($newComment);
33
34// 6. prepend メソッドは複数のノードや文字列を引数として受け取ることができます。
35//    例: $dom->prepend($anotherComment, $anotherElement, '<!-- 別のテキストコメント -->');
36//    ここでは単純な例として1つのノードを追加します。
37
38echo "--- prepend実行後のDOM構造 ---" . PHP_EOL;
39echo $dom->saveHTML() . PHP_EOL;
40
41/*
42上記のコードを実行すると、以下のようなHTMLが出力されます (DOCTYPE宣言は環境により自動付加されます):
43
44--- prepend実行前のDOM構造 ---
45<!DOCTYPE html>
46<html>
47  <body>
48    <p>これは既存のパラグラフです。</p>
49  </body>
50</html>
51
52--- prepend実行後のDOM構造 ---
53<!DOCTYPE html>
54<!-- これはprependで追加されたコメントです。 -->
55<html>
56  <body>
57    <p>これは既存のパラグラフです。</p>
58  </body>
59</html>
60*/

PHPのDOMDocument::prependメソッドは、DOMDocumentまたはDOMNodeオブジェクトの子ノードリストの先頭に、新しいノードや文字列を追加するために使用します。このメソッドはPHP 8以降で使用可能です。引数には、DOMNodeオブジェクトまたは文字列を複数指定できます。これらの引数は、子ノードリストの先頭に順番に追加されます。戻り値はありません。

サンプルコードでは、まずDOMDocumentオブジェクトを生成し、HTML構造を構築しています。具体的には、<html>、<body>、<p>要素を順に作成し、親子関係を設定しています。prependメソッドを使用する前に、現在のDOM構造を出力しています。

次に、createCommentメソッドでコメントノードを作成し、prependメソッドを使ってDOMDocumentの子ノードリストの先頭に追加しています。この例では、DOMDocumentの直下、つまり<html>タグの前にコメントが挿入されます。prependの実行後、再度DOM構造を出力し、変更点を確認します。

このメソッドを使うことで、既存のHTMLやXMLドキュメントの構造を、簡単に変更できます。例えば、DOCTYPE宣言やコメントを先頭に追加する際に役立ちます。prependは、DOM操作において、ノードを先頭に挿入するための便利な機能です。

DOMDocument::prependメソッドは、DOMDocumentまたはDOMNodeの子ノードリストの先頭にノードや文字列を追加します。PHP 8.0以降で使用可能です。引数にはDOMNodeオブジェクトまたは文字列を指定できます。

注意点として、DOMDocumentにprependする場合、通常はルート要素（<html>など）の前にノードが挿入されることを理解しておきましょう。HTML文書構造を意識して、意図した位置にノードが挿入されるか確認が必要です。

また、prependは複数のノードを一度に追加できます。ノードの追加に失敗した場合、エラーは発生しません。処理結果はsaveHTML()などで確認しましょう。

prependの対象となるノードがドキュメントに存在しない場合（新たにcreateElementで作ったノードなど）、自動的にドキュメントに追加されるわけではありません。明示的にappendChildなどで追加する必要があります。

PHP DOMDocumentで要素・ノード・文字列を先頭に追加する


1<?php
2
3// DOMDocumentを新規作成
4$dom = new DOMDocument('1.0', 'UTF-8');
5
6// ルート要素を作成
7$root = $dom->createElement('root');
8$dom->appendChild($root);
9
10// prependする要素を作成
11$newElement = $dom->createElement('newElement', '新しい要素');
12
13// テキストノードを作成
14$newTextNode = $dom->createTextNode("テキストノード");
15
16// 文字列をテキストノードとして追加
17$newString = "文字列";
18
19// prependを実行
20$root->prepend($newElement, $newTextNode, $newString);
21
22// 結果を出力
23echo $dom->saveXML();
24
25?>

PHPのDOMDocumentクラスにおけるprependメソッドは、指定したノードまたは文字列を、要素の最初の子ノードとして挿入する機能を提供します。このメソッドはPHP 8以降で使用可能です。

サンプルコードでは、まずDOMDocumentオブジェクトを新規に作成し、XMLドキュメントの構造を構築します。createElementメソッドでルート要素として<root>を作成し、ドキュメントに追加しています。

次に、prependメソッドに渡す要素やテキストノード、文字列を準備します。createElementで<newElement>を作成し、createTextNodeでテキストノードを作成、そして単純な文字列を準備します。

$root->prepend($newElement, $newTextNode, $newString)の行で、prependメソッドを実行しています。ここでは、$newElement（要素）、$newTextNode（テキストノード）、$newString（文字列）の３つを引数として渡しています。prependメソッドはこれらの引数を<root>要素の最初の子ノードとして順番に挿入します。複数のノードや文字列を一度に先頭に追加できる点が特徴です。

prependメソッドは戻り値を持ちません（void）。実行後、saveXMLメソッドを使ってXMLドキュメント全体を文字列として出力することで、prependメソッドの効果を確認できます。出力結果は、<root>要素の子要素として、<newElement>、テキストノード、文字列がこの順で挿入されたXML構造になります。

DOMDocument::prepend()メソッドは、指定したノードを要素の最初に追加します。引数にはDOMNodeオブジェクトまたは文字列を複数指定できます。文字列を渡した場合、テキストノードとして扱われます。

注意点として、prependはPHP 8で導入された比較的新しいメソッドであるため、古いバージョンのPHPでは動作しません。また、prependは要素の内容を直接変更するため、予期せぬ結果にならないよう、対象の要素を正しく指定する必要があります。大規模なXMLドキュメントを扱う場合は、メモリ消費量にも注意が必要です。DOMDocumentの操作は、XML構造を理解していることが前提となります。