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

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

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

基本的な使い方

namedItemメソッドは、DOMHTMLCollectionオブジェクト内の特定の名前を持つノードを取得するメソッドです。このメソッドは、HTMLCollectionに格納されている要素の中から、name属性の値が指定された文字列と一致する最初の要素を返します。もし該当する要素が見つからない場合は、nullを返します。

具体的には、HTMLドキュメント内で、例えば<input>要素のようにname属性を持つ要素が複数存在する場合、このメソッドを使用することで、特定の名前を持つ要素を効率的に取得できます。このメソッドは、コレクション内の要素を順番に検索し、最初にname属性が一致した要素を返します。

このメソッドは、動的に生成されたHTML要素を操作する際や、フォーム要素をプログラムから操作する場合に特に有用です。例えば、JavaScriptを使用してフォームの入力値を検証する際に、namedItemメソッドを使って特定の入力フィールドを取得し、その値を取得したり、変更したりすることができます。

namedItemメソッドを使用することで、HTMLCollection内の要素にアクセスする際に、数値インデックスを使用する代わりに、意味のある名前を使用して要素を特定できます。これにより、コードの可読性と保守性が向上します。また、HTML構造が変更された場合でも、名前による参照を使用していれば、インデックスに依存する場合に比べて、コードの変更を最小限に抑えることができます。

構文(syntax)


1public Dom\Node|null Dom\HTMLCollection::namedItem(string $name)

引数(parameters)

string $key

string $key: 取得したい要素のname属性またはid属性を指定する文字列

戻り値(return)

?Dom\Element

指定された名前（name）に一致する要素を返します。一致する要素が見つからない場合は null を返します。

サンプルコード

PHP HTMLCollection namedItem で要素を探す


1<?php
2
3// Dom\HTMLCollection::namedItem メソッドの使用例
4// このサンプルコードはPHP 8.3以降のDOM拡張で導入されたDom\HTMLCollectionクラスを使用しています。
5// Dom\HTMLCollection は、HTML要素のコレクション（配列に似た構造）を表します。
6function demonstrateNamedItemUsage(): void
7{
8    // HTML文字列を準備
9    // ここでは、name属性とid属性を持つinput要素を含むフォームを定義しています。
10    $html = <<<HTML
11<!DOCTYPE html>
12<html>
13<head>
14    <title>Named Item Example</title>
15</head>
16<body>
17    <form id="myForm">
18        <input type="text" name="username" value="John Doe">
19        <input type="password" name="password" id="pass_field">
20        <button type="submit" name="submitButton">Submit</button>
21    </form>
22    <div>
23        <input type="email" name="user_email" value="test@example.com">
24    </div>
25</body>
26</html>
27HTML;
28
29    // Dom\HTMLDocument のインスタンスを作成し、HTMLをロードします。
30    // Dom\HTMLDocument::getElementsByTagName などのメソッドは Dom\HTMLCollection を返します。
31    $document = new Dom\HTMLDocument();
32    $document->loadHTML($html);
33
34    // ドキュメント内のすべての 'input' 要素のコレクションを取得します。
35    // このメソッドは Dom\HTMLCollection のインスタンスを返します。
36    $inputs = $document->getElementsByTagName('input');
37
38    echo "--- Dom\\HTMLCollection::namedItem の使用例 ---" . PHP_EOL . PHP_EOL;
39
40    // namedItem() メソッドを使用して、'username' という名前の input 要素を取得します。
41    // namedItem() は、コレクション内の要素の中から、name属性またはid属性が引数($key)と一致する最初の要素を返します。
42    $usernameInput = $inputs->namedItem('username');
43    if ($usernameInput !== null) {
44        echo "1. 名前が 'username' の要素が見つかりました:" . PHP_EOL;
45        echo "   タグ名: " . $usernameInput->tagName . PHP_EOL;
46        echo "   name属性: " . ($usernameInput->getAttribute('name') ?? 'なし') . PHP_EOL;
47        echo "   value属性: " . ($usernameInput->getAttribute('value') ?? 'なし') . PHP_EOL;
48    } else {
49        echo "1. 名前が 'username' の要素は見つかりませんでした。" . PHP_EOL;
50    }
51
52    echo PHP_EOL;
53
54    // namedItem() メソッドは name属性だけでなく、id属性も検索対象とします。
55    // 'pass_field' というIDを持つ input 要素を取得します。
56    $passwordIdInput = $inputs->namedItem('pass_field');
57    if ($passwordIdInput !== null) {
58        echo "2. IDが 'pass_field' の要素が見つかりました:" . PHP_EOL;
59        echo "   タグ名: " . $passwordIdInput->tagName . PHP_EOL;
60        echo "   id属性: " . ($passwordIdInput->getAttribute('id') ?? 'なし') . PHP_EOL;
61        echo "   name属性: " . ($passwordIdInput->getAttribute('name') ?? 'なし') . PHP_EOL;
62    } else {
63        echo "2. IDが 'pass_field' の要素は見つかりませんでした。" . PHP_EOL;
64    }
65
66    echo PHP_EOL;
67
68    // コレクション内に存在しない名前/IDの要素を検索した場合、namedItem() は null を返します。
69    $nonExistentInput = $inputs->namedItem('nonExistentKey');
70    if ($nonExistentInput === null) {
71        echo "3. 名前/IDが 'nonExistentKey' の要素はコレクション内に見つかりませんでした (期待通り)。" . PHP_EOL;
72    }
73}
74
75// 関数を実行します。
76demonstrateNamedItemUsage();

PHP 8.3以降で利用できるDOM拡張のDom\HTMLCollection::namedItemメソッドは、HTMLドキュメント内の要素の集合（コレクション）の中から、特定の要素を名前やIDで効率的に見つけ出すための機能です。

このメソッドは、Dom\HTMLCollectionというクラスに属しており、これはウェブページ上の複数のHTML要素（例えば、すべての<input>タグ）をまとめて扱う際に用いられます。Dom\HTMLDocument::getElementsByTagNameなどのメソッドは、このDom\HTMLCollectionのインスタンスを返します。

namedItemメソッドは、引数として文字列の$keyを受け取ります。この$keyは、あなたが探したいHTML要素のname属性またはid属性の値を指定します。メソッドはコレクションの中から、この$keyに一致するname属性かid属性を持つ最初の要素を見つけ出し、Dom\Elementオブジェクトとして返します。もし該当する要素が見つからない場合はnullが返されます。

サンプルコードでは、まずHTML文字列を準備し、Dom\HTMLDocumentに読み込ませています。次に、すべてのinput要素をDom\HTMLCollectionとして取得した後、namedItem('username')を使ってname="username"の入力欄を取得する例を示しています。また、namedItem('pass_field')ではid="pass_field"の入力欄を取得しており、namedItemがid属性も検索対象とすることが分かります。このように、HTML要素をname属性やid属性で直接指定して取得できるため、PHPでフォームデータを扱う際など、まるで連想配列のキーで要素にアクセスするような感覚で、特定のHTML要素に容易にアクセスできるようになります。存在しないキーを指定した場合はnullが返されるため、要素の有無を安全に確認することも可能です。

Dom\HTMLCollection::namedItemメソッドは、HTML要素のコレクションの中から、name属性またはid属性が指定されたキーと一致する最初の要素を見つけます。一致する要素が見つからない場合はnullを返しますので、利用する前に必ずnullチェックを行い、存在を確認してください。複数の要素が同じnameやidを持つ場合でも、最初に見つかった要素のみが返される点にご注意ください。また、このメソッドはPHP 8.3以降のDOM拡張で利用可能であり、古いPHPバージョンでは動作しません。取得した要素はDom\Elementオブジェクトとして扱われ、その属性やタグ名をgetAttributeなどのメソッドで取得できます。

PHP: namedItemでname/id要素を取得する


1<?php
2
3// Dom\HTMLCollection::namedItem() の使用例
4// システムエンジニアを目指す初心者向けに、HTML要素の「name」または「id」属性を使って特定の要素を取得する方法を示します。
5
6/**
7 * HTML文字列から指定した名前またはIDの要素を取得するサンプル関数。
8 *
9 * @param string $htmlString 処理対象のHTML文字列。
10 */
11function demonstrateNamedItem(string $htmlString): void
12{
13    // 1. 新しいDom\Documentインスタンスを作成します。
14    //    これはHTMLドキュメントをPHPで操作するための基盤となります。
15    $dom = new Dom\Document();
16
17    // 2. HTML文字列をロードします。
18    //    LIBXML_HTML_NOIMPLIED と LIBXML_HTML_NODEFDTD は、
19    //    <html><body>タグやDOCTYPE宣言が自動で追加されるのを防ぎ、
20    //    指定したHTMLをそのままパースするのに役立ちます。
21    $dom->loadHTML($htmlString, LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
22
23    // 3. ドキュメント内のすべての要素からなるDom\HTMLCollectionを取得します。
24    //    PHP 8では、getElementsByTagName('*') メソッドは Dom\HTMLCollection オブジェクトを返します。
25    //    このコレクションは、ドキュメント内のすべての要素を含みます。
26    $elements = $dom->getElementsByTagName('*');
27
28    echo "--- Dom\\HTMLCollection::namedItem() の使用例 ---\n";
29    echo "ロードされたHTML:\n" . $htmlString . "\n\n";
30
31    // 4. namedItemメソッドを使用して、特定のname属性またはid属性を持つ要素を取得します。
32    //    このメソッドは、コレクション内から指定されたキー（nameまたはid）に一致する最初の要素を返します。
33
34    // 'username'というname属性を持つ<input>要素を取得します。
35    $usernameElement = $elements->namedItem('username');
36    if ($usernameElement instanceof Dom\Element) {
37        echo "name='username' の要素が見つかりました。\n";
38        echo "  タグ名: " . $usernameElement->tagName . "\n";
39        echo "  name属性: " . $usernameElement->getAttribute('name') . "\n";
40        echo "  value属性: " . $usernameElement->getAttribute('value') . "\n\n";
41    } else {
42        echo "name='username' の要素は見つかりませんでした。\n\n";
43    }
44
45    // 'useremail'というid属性を持つ<input>要素を取得します。
46    $useremailElement = $elements->namedItem('useremail');
47    if ($useremailElement instanceof Dom\Element) {
48        echo "id='useremail' の要素が見つかりました。\n";
49        echo "  タグ名: " . $useremailElement->tagName . "\n";
50        echo "  id属性: " . $useremailElement->getAttribute('id') . "\n";
51        echo "  value属性: " . $useremailElement->getAttribute('value') . "\n\n";
52    } else {
53        echo "id='useremail' の要素は見つかりませんでした。\n\n";
54    }
55
56    // 'info'というname属性を持つ<div>要素を取得します。
57    $infoElement = $elements->namedItem('info');
58    if ($infoElement instanceof Dom\Element) {
59        echo "name='info' の要素が見つかりました。\n";
60        echo "  タグ名: " . $infoElement->tagName . "\n";
61        echo "  name属性: " . $infoElement->getAttribute('name') . "\n";
62        echo "  テキスト内容: " . $infoElement->textContent . "\n\n";
63    } else {
64        echo "name='info' の要素は見つかりませんでした。\n\n";
65    }
66
67    // 存在しないnameまたはidを指定した場合、nullが返されます。
68    $nonExistentElement = $elements->namedItem('nonexistent');
69    if ($nonExistentElement === null) {
70        echo "nameまたはid='nonexistent' の要素は存在しませんでした (nullが返されました)。\n\n";
71    }
72}
73
74// サンプルとして使用するHTML文字列。
75// ここには、name属性とid属性を持ついくつかのHTML要素が含まれています。
76$sampleHtml = <<<HTML
77<form>
78    <label for="username">ユーザー名:</label>
79    <input type="text" name="username" value="John Doe">
80    <br>
81    <label for="useremail">メールアドレス:</label>
82    <input type="email" id="useremail" value="john@example.com">
83    <br>
84    <div name="info">これは追加情報です。</div>
85    <p>その他のフォーム要素...</p>
86</form>
87HTML;
88
89// 関数を実行し、Dom\HTMLCollection::namedItem() の動作を確認します。
90demonstrateNamedItem($sampleHtml);
91
92?>

Dom\HTMLCollection::namedItem()は、PHPでHTMLドキュメント内の特定の要素を効率的に検索するためのメソッドです。このメソッドを利用すると、HTML要素が持つ「name」属性や「id」属性を使って、目的の要素をピンポイントで取得できます。

メソッドはDom\HTMLCollectionオブジェクトに適用され、引数string $keyとして検索したい要素のnameまたはid属性の値を指定します。戻り値は、指定した$keyに合致する最初のDom\Elementオブジェクトです。もし一致する要素が見つからない場合はnullが返されるため、要素の存在を確認しながら安全に処理を進めることができます。

サンプルコードでは、与えられたHTML文字列をDom\Documentに読み込み、そのドキュメント内の全要素からなるDom\HTMLCollectionを作成しています。次に、このコレクションに対してnamedItem()メソッドを使用し、「username」というname属性や「useremail」というid属性を持つ<input>要素などを取得しています。要素が存在しない場合のnullの挙動も示されており、HTMLドキュメントから特定の要素を正確に探し出す基本的な方法がわかりやすく説明されています。

namedItemメソッドは、HTML要素のname属性またはid属性を利用して、特定の要素を効率的に取得する際に役立ちます。引数に指定したキーと一致する属性を持つ要素がコレクション内に存在すればDom\Elementオブジェクトが返されますが、見つからない場合はnullが戻り値となります。そのため、取得した要素を操作する前に、if ($element instanceof Dom\Element)のように必ずnullでないことを確認することが重要です。この確認を怠ると、存在しない要素に対して操作を行おうとしてエラーが発生する可能性があります。また、同じnameやidを持つ要素が複数存在する場合でも、namedItemは最初に見つかった一つだけを返しますのでご注意ください。このメソッドは、特にフォーム要素などname属性が重要な要素を扱う際に便利です。