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

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

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

基本的な使い方

prependメソッドは、Dom\DocumentFragmentオブジェクトの子ノードのリストの先頭に、新しいノードを追加するメソッドです。

Dom\DocumentFragmentは、HTMLやXML文書のDOM（Document Object Model）操作において、一時的に複数のノードをまとめて扱うための軽量なオブジェクトです。これは実際の文書ツリーの一部を表現しますが、それ自体が直接レンダリングされることはなく、通常の文書に挿入されるまで動作しません。そのため、複数のDOMノードを一度に構築し、その後にまとめて実際の文書に追加するような場合に、パフォーマンス上の利点がある中間コンテナとして利用されます。

このprependメソッドを使用すると、一つまたは複数のDom\Nodeオブジェクトを引数として渡し、それらを対象のDom\DocumentFragmentオブジェクトが保持する子ノードのリストの最も先頭に挿入することができます。たとえば、既存の子ノードが既に複数ある場合、新しく追加されたノードはそれらすべてよりも前、つまり論理的な順序で一番最初に配置されます。引数として渡されたノードがすでに他のDOMツリー内にある場合、そのノードは元の場所から削除され、現在のDocumentFragmentの先頭に移動します。

この機能は、動的に生成した複数の要素を既存の要素の先頭にまとめて追加する際に特に有用です。これにより、DOM操作の回数を減らし、ウェブページの応答性を向上させることができます。prependメソッドはノードの追加操作を実行するだけで、特定の値を返すことはありません。

構文(syntax)


1<?php
2
3$dom = new DOMDocument();
4$fragment = $dom->createDocumentFragment();
5
6$fragment->prepend(
7    $dom->createElement('p', '新しい段落'),
8    $dom->createTextNode('先頭に追加されるテキスト'),
9    'さらに追加される文字列'
10);
11
12?>

引数(parameters)

Dom\Node|string ...$nodes

Dom\Node|string $nodes: 追加したいDOMノードまたはHTML文字列。複数指定可能です。

戻り値(return)

void

このメソッドは、指定されたノードをドキュメントフラグメントの先頭に挿入します。戻り値はありません。

サンプルコード

PHP DomDocumentFragment::prependでノードを追加する


1<?php
2
3// ドキュメントフラグメントを作成
4$df = new DOMDocumentFragment();
5
6// ドキュメントを作成
7$dom = new DOMDocument();
8$dom->loadHTML('<!DOCTYPE html><html><head><title>Test</title></head><body><div id="container"></div></body></html>');
9
10// container要素を取得
11$container = $dom->getElementById('container');
12
13// prependするノードを作成
14$newNode1 = $dom->createElement('p', 'This is the first new paragraph.');
15$newNode2 = $dom->createElement('p', 'This is the second new paragraph.');
16
17// ドキュメントフラグメントにノードを追加
18$df->prepend($newNode1, $newNode2);
19
20// containerにドキュメントフラグメントをprepend
21$container->prepend($df);
22
23// 結果を出力
24echo $dom->saveHTML();
25
26?>

このPHPのサンプルコードは、Dom\DocumentFragmentクラスのprependメソッドの使い方を示しています。prependメソッドは、指定されたノード（Dom\Nodeオブジェクトまたは文字列）を、ドキュメントフラグメントの先頭に追加するメソッドです。

まず、DOMDocumentFragmentオブジェクトを作成し、次にDOMDocumentオブジェクトを作成してHTMLをロードします。getElementByIdメソッドを使って、HTML内のcontainer要素を取得します。

prependするノードとして、createElementメソッドを使って2つの<p>要素を新たに作成します。

prependメソッドは可変長引数を受け取ります。この例では、作成した2つの<p>要素を引数として$df->prepend($newNode1, $newNode2)のように呼び出すことで、ドキュメントフラグメント$dfの先頭にこれらの要素が追加されます。

その後、$container->prepend($df)によって、ドキュメントフラグメント$dfの内容がcontainer要素の先頭に追加されます。これにより、container要素の中に、新しく作成した2つの<p>要素が、既存のコンテンツよりも前に挿入されます。

prependメソッドの戻り値はvoidです。つまり、このメソッドは値を返しません。saveHTMLメソッドを使用して結果のHTMLを出力すると、<div id="container">要素の中に、追加された2つの<p>要素が先頭に表示されることが確認できます。このサンプルコードは、動的にHTML要素を生成し、既存の要素の先頭に挿入する方法を学ぶ上で役立ちます。

Dom\DocumentFragment::prependメソッドは、指定したノードをドキュメントフラグメントの先頭に追加します。複数のノードを一度に追加できます。このサンプルコードでは、まずDOMDocumentFragmentを作成し、その後、prependするノードをcreateElementで作成しています。重要な点として、追加するノードは同じDOMDocumentのインスタンスから生成する必要があります。異なるDOMDocumentのノードを追加しようとするとエラーが発生する可能性があります。また、prependはvoid型なので、戻り値はありません。prependされた結果は、saveHTMLなどで確認してください。

PHP DomDocumentFragment prependでノードを追加する


1<?php
2
3// ドキュメントフラグメントを作成
4$fragment = new DOMDocumentFragment();
5
6// テキストノードを作成
7$text1 = new DOMText("Hello, ");
8$text2 = new DOMText("world!");
9
10// フラグメントにテキストノードを追加
11$fragment->prepend($text2, $text1);
12
13// 結果を表示 (この例では DOMDocument が必要ですが、prepend の動作を示すため DOMDocumentFragment を使用しています)
14$dom = new DOMDocument();
15$dom->appendChild($dom->importNode($fragment, true));
16echo $dom->saveHTML(); // 出力: Hello, world!

PHPのDom\DocumentFragmentクラスにおけるprependメソッドは、複数のノードまたは文字列を、ドキュメントフラグメントの先頭に追加する機能を提供します。このメソッドは引数として、追加したいDom\Nodeオブジェクトまたは文字列を可変長引数...$nodesとして受け取ります。複数のノードや文字列を一度に追加することが可能です。

サンプルコードでは、まずDOMDocumentFragmentのインスタンスを作成しています。これは、複数のノードを一時的に保持するためのコンテナとして機能します。次に、DOMTextクラスを用いて2つのテキストノード("Hello, "と"world!")を作成し、prependメソッドを使ってこれらのノードをフラグメントの先頭に追加しています。この際、prependメソッドは引数の順序でノードを追加するため、$text2、$text1の順で指定することで、最終的なノードの順序が"Hello, world!"となるようにしています。

prependメソッドは戻り値として何も返しません(void)。フラグメントの内容は直接変更されます。サンプルコードでは、フラグメントの内容を確認するために、DOMDocumentを作成し、フラグメントの内容をインポートして表示しています。DOMDocumentFragment自体はDOMツリーの一部ではないため、表示するにはDOMDocumentにインポートする必要があります。この例ではprependメソッドが指定されたノードを、ドキュメントフラグメントの先頭に正しく追加していることを確認できます。

DOMDocumentFragment::prependメソッドは、引数に指定したノードまたは文字列を、フラグメントの先頭に追加します。複数の引数を指定した場合、指定した順に先頭へ挿入されます。サンプルコードでは$text2、$text1の順で指定しているため、結果として"Hello, world!"の順で表示されます。このメソッドはvoidを返すため、戻り値を直接利用することはできません。また、サンプルコードはDOMDocumentFragmentの動作を示すためのもので、実際にHTMLとして出力するにはDOMDocumentへの追加が必要です。DOMDocument::importNodeを使用することで、DOMDocumentFragmentの内容をDOMDocumentに安全にコピーできます。