- カテゴリ: helper
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
head(array $array): mixed - 関連:
last/Arr::first/Collection::first/array_key_first - 変更履歴: ―
要点（TL;DR）
- 配列の最初の要素の値を1件だけ取り出す
head($array)- 罠：
- 空配列は
nullを返す（デフォルト値は持たない） - コレクションは渡さない（
$collection->first()を使う） - 先頭キーは取れない（
array_key_first()を使う）
- 空配列は
概要
head() は与えた配列の先頭の値を返す小さなヘルパーです。カーソル（内部ポインタ）を動かさないため、reset() のような副作用がありません。最初の要素だけ欲しい場面（先頭レコード・先頭ID・最初の設定値など）で、簡潔に書けます。
構文 / シグネチャ
mixed head(array $array)
- 引数（表）
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
$array | array | ✅ | なし | 先頭要素を取りたい配列 |
- 戻り値：
mixed|null— 配列の先頭要素の値。空配列はnull。 - 例外/副作用：例外なし。配列の内部ポインタは変更されない。
使用例
最小例
<?php
$ids = [10, 11, 12];
$first = head($ids); // 10
var_dump($first); // int(10)
実務例
<?php
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\DB;
// 例1: リクエスト配列の先頭値を取りたい（空なら 'N/A' にフォールバック）
$tags = request()->input('tags', []); // ['news', 'tech'] など
$firstTag = head($tags) ?? 'N/A';
// 例2: DBから取得したIDリストの先頭ID
$ids = DB::table('posts')->where('status', 'published')->pluck('id')->all();
$firstId = head($ids); // 先頭の投稿ID
// 例3: 「配列かもしれない/単体値かもしれない」入力を安全に先頭取得
$maybeArray = request('category'); // 'book' または ['book', 'tech'] など
$firstCategory = head(Arr::wrap($maybeArray)); // いつでも先頭の値だけ取れる
よくある落とし穴・注意
- 空配列は
null：デフォルト値はないため、head($a) ?? 'default'のように合わせて使う。 - コレクションは非推奨：
head($collection->all())は配列化でメモリコストが増える。$collection->first()を使う。 - キーは取れない：
head()は値のみ。キーが欲しいならarray_key_first()。 reset()との違い：reset()は内部ポインタを動かすが、head()は非破壊。
代替・関連APIとの比較
Arr::first($array, $callback = null, $default = null)：コールバックやデフォルトが必要ならこちら。条件付きで「最初に合致する要素」を返せる。last($array)：末尾の値を取りたいとき。Collection::first()：コレクションの先頭要素。LazyCollection でも遅延のまま取得可能。array_key_first($array)（PHP）：先頭キーが必要なとき。reset($array)（PHP）：先頭へポインタを移動し、現在の値を返す。副作用あり。
選定基準
- シンプルに「先頭の値」→
head() - 条件・デフォルトが必要→
Arr::first() - コレクション→
Collection::first() - 先頭キー→
array_key_first() - ポインタを使うレガシー処理→
reset()（推奨度低）
テスト例（Pest）
<?php
it('gets the first element from array', function () {
expect(head([3, 4, 5]))->toBe(3);
});
it('returns null for empty array', function () {
expect(head([]))->toBeNull();
});
it('works with wrapped single value', function () {
$value = head(\Illuminate\Support\Arr::wrap('x'));
expect($value)->toBe('x');
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
null が返る | 空配列だった | head($a) ?? 'default' でデフォルトを用意 |
| メモリ使用量が増える | コレクションを ->all() で配列化して head() | 直接 $collection->first() を使う |
| 先頭キーが欲しい | head() は値のみ取得 | array_key_first($array) を使う |
| 期待と違う要素が返る | 事前の並び替えが想定と不一致 | sort/orderBy/ksort 等で並び順を明示 |
参考リンク
- Laravel Docs: Helpers —
head()
https://laravel.com/docs/12.x/helpers#method-head - Laravel Docs: Helpers —
last()
https://laravel.com/docs/12.x/helpers#method-last - Laravel Docs: Collections —
first()
https://laravel.com/docs/12.x/collections#method-first - Laravel Source:
Illuminate\Support\Arr::first()（GitHub）
https://github.com/laravel/framework/blob/12.x/src/Illuminate/Support/Arr.php - PHP Manual:
array_key_first
https://www.php.net/array_key_first - PHP Manual:
reset
https://www.php.net/reset
