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

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

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

基本的な使い方

prependメソッドは、Dom\XMLDocumentクラスに属し、XMLドキュメントの直接の子ノードの先頭に新しいノードを追加するメソッドです。

このメソッドを使用すると、既存のXMLドキュメントオブジェクトに対して、指定されたDom\Nodeオブジェクトを、現在の全ての子ノードの前に挿入できます。具体的には、XMLドキュメントの最上位レベル、つまりドキュメント要素（ルート要素）や既存の処理命令、コメントなどの前に、新しいノードを追加する際に利用されます。

例えば、XML宣言の直後に特別なコメントを追加したり、処理命令をドキュメントの先頭に配置したりする場合に役立ちます。引数としては、追加したいノードを表すDom\Nodeオブジェクトを指定します。成功した場合、このメソッドは何も返しません（void）。

XMLドキュメントの構造を操作する際には、XMLの妥当性（well-formedness）と有効性（validity）を維持することが重要です。このメソッドでノードを追加する際は、XMLの構造規則、例えばドキュメント要素は一つだけであるといった制約に違反しないように注意が必要です。誤ったノードを追加すると、XMLドキュメントが破損したり、意図しない挙動を引き起こしたりする可能性があります。

このprependメソッドは、プログラムによってXMLドキュメントの構造を動的に変更し、特定の情報や命令をドキュメントの冒頭に追加したい場合に、非常に強力なツールとなります。

構文(syntax)


1<?php
2
3$xmlDocument = new Dom\XMLDocument();
4$xmlDocument->loadXML('<root><item>既存の要素</item></root>');
5
6// 新しいノード（ここではコメントノード）を作成します。
7$newComment = $xmlDocument->createComment('これは最初に追加されたコメントです。');
8
9// ドキュメントの最初の子ノードとして新しいノードを追加します。
10$xmlDocument->prepend($newComment);
11
12// 結果のXMLを出力します。
13echo $xmlDocument->saveXML();
14
15?>

引数(parameters)

Dom\Node|string ...$nodes

Dom\Node|string ...$nodes: 追加するDom\NodeオブジェクトまたはXML文字列の可変長引数リスト

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

Dom\XMLDocument::prependで要素を追加する


1<?php
2
3// XMLDocument を作成
4$dom = new DOMDocument('1.0', 'UTF-8');
5
6// ルート要素を作成
7$root = $dom->createElement('root');
8$dom->appendChild($root);
9
10// prepend する要素を作成
11$element1 = $dom->createElement('element1', 'value1');
12$element2 = $dom->createElement('element2', 'value2');
13
14// root要素に prepend で要素を追加
15$root->prepend($element1, $element2);
16
17// 結果を表示 (オプション)
18echo $dom->saveXML();

PHPのDOMDocumentクラスにおけるprependメソッドは、指定されたノードをXMLドキュメントの特定の位置に、先頭に追加するために使用します。このメソッドはPHP 8以降で使用できます。

上記のサンプルコードでは、まずDOMDocumentオブジェクトを作成し、XMLドキュメントのルート要素として<root>要素を追加しています。次に、prependメソッドを使って<root>要素の先頭に新しい要素を追加します。

prependメソッドは、引数としてDOMNodeオブジェクトまたは文字列を複数受け取ることができます。この例では、<element1>と<element2>という2つの新しい要素を作成し、それぞれ'value1'と'value2'というテキストノードを子として追加しています。そして、これらの要素を$root->prepend($element1, $element2);というコードで、<root>要素の先頭に追加しています。prependメソッドは、指定された要素を引数の順番通りに先頭に追加します。そのため、<element2>が<element1>の前に配置されます。

prependメソッドの戻り値はありません。XMLドキュメントの内容は、$dom->saveXML()で確認できます。このメソッドを使うことで、XMLドキュメント構造を動的に変更し、より複雑なXMLドキュメントを生成することが可能になります。

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

注意点として、prependはPHP 8から利用可能なメソッドです。それ以前のバージョンでは動作しません。また、追加するノードが既にドキュメントに存在する場合、移動されます。prependメソッドは値を返さないため、追加の成否を直接確認することはできません。エラーが発生した場合は例外がスローされます。XML構造が不正にならないように、追加するノードの種類と位置関係には注意が必要です。

PHP Dom\XMLDocument::prependでテキストを先頭に追加する


1<?php
2
3// XMLドキュメントを作成
4$dom = new DOMDocument('1.0', 'UTF-8');
5
6// ルート要素を作成
7$root = $dom->createElement('root');
8$dom->appendChild($root);
9
10// 子要素を作成
11$child1 = $dom->createElement('child1', '既存のテキスト');
12$root->appendChild($child1);
13
14// 追加するノード（テキスト）を作成
15$newNode = $dom->createTextNode('先頭に追加するテキスト');
16
17// 先頭にノードを追加
18$child1->prepend($newNode);
19
20// 結果を出力
21echo $dom->saveXML();
22
23?>

PHPのDOMDocumentクラスにおけるprependメソッドは、特定のノードの先頭に新しいノードまたはテキストを追加するために使用されます。このメソッドは、PHP 8以降で使用可能です。

このサンプルコードでは、まずDOMDocumentオブジェクトを作成し、XMLドキュメントの基本的な構造を構築しています。具体的には、ルート要素として<root>を作成し、その子要素として<child1>を作成、さらにテキストノードを<child1>に追加しています。

prependメソッドは、この<child1>要素に対して、指定されたノードを先頭に追加するために使用されます。サンプルコードでは、createTextNodeメソッドを使って新しいテキストノードを作成し、それをprependメソッドの引数として渡しています。

$child1->prepend($newNode);の行が、prependメソッドの実行箇所です。このコードによって、$newNode（'先頭に追加するテキスト'というテキストノード）が、$child1要素の内容の先頭に挿入されます。

prependメソッドは引数として、DOMNodeオブジェクトまたは文字列を受け取ります。複数のノードを引数として指定することも可能です。このメソッドは戻り値を持ちません。つまり、処理の成否を直接的な戻り値で判断するのではなく、例外処理などを用いて確認する必要があります。

最後に、saveXMLメソッドを使ってXMLドキュメント全体を文字列として出力し、prependメソッドによる変更が反映されていることを確認しています。このサンプルコードを実行すると、<child1>要素の内容が、指定されたテキストで始まるように変更されていることがわかります。prependメソッドは、既存のXMLドキュメント構造を動的に変更する際に非常に便利なメソッドです。

DOMElement::prependメソッドは、指定した要素の最初の子ノードとして、引数で与えられたノード（または文字列）を追加します。このメソッドは、PHP 8以降で使用可能です。

注意点として、引数にはDOMNodeオブジェクトまたは文字列を渡す必要があります。文字列を渡した場合、自動的にテキストノードとして扱われます。prependメソッドは対象のノードを変更しますが、戻り値はありません。XMLドキュメントの構造を操作する際は、ノードの親子関係に注意し、意図しない場所にノードが追加されないように確認してください。また、追加する文字列にXMLとして不正な文字が含まれていないか注意が必要です。