wrap — 単一値や配列をコレクションに包む
collection
- カテゴリ: collection
- 掲載バージョン: Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド:
Illuminate\Support\Collection::wrap
- 関連:
collect / Illuminate\Support\Collection::make / Illuminate\Support\Arr::wrap / Illuminate\Support\LazyCollection::wrap
- 変更履歴: 5.x 以降で提供（Laravel 10〜12 で仕様差分ほぼなし）
要点（TL;DR）
- 何に使うか：スカラー値・配列・コレクションを問わず、必ず Collection インスタンスに揃えるためのヘルパー
- 最低限の使い方：
$collection = Collection::wrap($value);
- よくある罠
- すでに
Collection の場合でも 新しいインスタンス が返る（同一オブジェクトではない）
null を渡すと 空コレクション になる（[null] ではない）- Eloquent の
Collection をそのまま static 呼び出しすると IDE が補完しづらい（use Illuminate\Support\Collection; 推奨）
概要
Collection::wrap は、渡された値が配列かどうかを意識せずに「とにかくコレクション化したい」ときに使う静的メソッドです。
フォーム入力、設定値、外部 API のレスポンスなど、配列だったり単一値だったりするケース を一度 Collection に揃えて処理したい場面で役立ちます。
is_array チェックや Arr::wrap のラップ処理を毎回書かずに済むため、前処理ロジックを簡潔にできます。
構文 / シグネチャ
use Illuminate\Support\Collection;
$collection = Collection::wrap(mixed $value): Collection;
引数
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|
| $value | mixed | ✅ | なし | コレクション化したい値。配列・Collection・Enumerable・スカラー・null など任意 |
戻り値
- 型:
Illuminate\Support\Collection
- 意味:
$value が
Collection / Enumerable のとき：その要素をコピーした新しい Collection- 配列のとき：その配列を要素に持つ Collection
- スカラー値のとき：
[$value] を要素に持つ Collection
null のとき：空の Collection（要素数 0）
例外 / 副作用
- 例外: なし（通常の使用では例外を投げない）
- 副作用: なし（引数が Collection の場合も非破壊で新インスタンスを返す）
使用例
最小例
<?php
use Illuminate\Support\Collection;
$value = 1;
$collection = Collection::wrap($value);
dump($collection->all()); // [1]
実務例：フォーム入力の単一/複数を同一処理に揃える
<?php
use Illuminate\Http\Request;
use Illuminate\Support\Collection;
Route::post('/tags', function (Request $request) {
// 'tags' が "php"（文字列）でも ["php", "laravel"]（配列）でも、Collection に統一
$tags = Collection::wrap($request->input('tags'))
->filter() // 空要素を除外
->unique() // 重複タグを除外
->values(); // 連番キーに整形
// ここから先は $tags を Collection 前提で処理できる
foreach ($tags as $tag) {
// タグごとの処理
}
return response()->json([
'tags' => $tags,
]);
});
よくある落とし穴・注意
- すでに Collection の場合でも新しいインスタンス
Collection::wrap($collection) は $collection と同じ要素を持ちますが、別オブジェクトです。- 元のコレクションをそのまま使いたいだけなら、ラップ不要です。
null が空コレクションになる
Collection::wrap(null) → collect([]) と同じ。null を要素として扱いたい場合は、自分で collect([null]) を使う必要があります。
- 計算量
- 内部的には配列コピーや
all() が走るため、O(n) の処理。
- 大きな配列やコレクションに対して頻繁に呼ぶと、無駄なコピーになることがあります。
- LazyCollection とは別物
- 遅延評価が欲しい場合は
Illuminate\Support\LazyCollection::wrap を使うか、LazyCollection での生成を検討してください。
代替・関連APIとの比較
collect($value)
- ほとんどのケースで同じ用途。
collect() はグローバル関数で、内部的に Collection::make / Collection のコンストラクタを使います。- プロジェクト方針として「静的メソッドで揃えたい」場合に
Collection::wrap を選択。
Collection::make($value)
make も値からコレクションを作りますが、実装・挙動がバージョンにより異なる部分があります。- 「配列か単一値かを意識せずとにかく配列化 → コレクション」のパターンを明示したいなら
wrap の方が意図が伝わりやすいです。
Arr::wrap($value)
- 返り値が「配列」である点が異なります。
- その後も配列として扱うなら
Arr::wrap、コレクションチェーンに乗せる前提なら Collection::wrap を使い分けます。
LazyCollection::wrap($value)
- 大量データやストリームを遅延評価で処理したい場合。
- 通常の
Collection は全要素をメモリに持つため、数十万件以上では LazyCollection の利用も検討。
入出力対応表（イメージ）
入力 $value | Collection::wrap($value)->all() |
|---|
1 | [1] |
'foo' | ['foo'] |
['a', 'b'] | ['a', 'b'] |
null | [] |
collect([1, 2]) | [1, 2] |
['id' => 1, 'name' => 'Laravel'] | ['id' => 1, 'name' => 'Laravel'] |
※ キーはそのまま保持 されます。
テスト例（Pest）
<?php
use Illuminate\Support\Collection;
it('wraps scalar value into collection', function () {
$collection = Collection::wrap('laravel');
expect($collection)->toBeInstanceOf(Collection::class)
->and($collection->all())->toBe(['laravel']);
});
it('wraps null as empty collection', function () {
$collection = Collection::wrap(null);
expect($collection->count())->toBe(0);
});
it('clones existing collection elements', function () {
$original = collect([1, 2, 3]);
$wrapped = Collection::wrap($original);
expect($wrapped->all())->toBe($original->all())
->and($wrapped)->not->toBe($original); // 別インスタンス
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|
Call to undefined method ...::wrap() | use Illuminate\Support\Collection; を忘れている、または別クラス名と衝突 | ファイル先頭で正しく use Illuminate\Support\Collection; を宣言する。別名を付ける場合は use Illuminate\Support\Collection as BaseCollection; などに統一 |
Call to a member function ... on null | Collection::wrap 結果ではなく、元の $value に対してメソッドを呼んでいる | 適切に $collection = Collection::wrap($value); を経由し、以降は $collection に対してメソッドチェーンする |
| メモリ使用量が増える | 大きな配列やコレクションに対して何度も wrap している | 同じデータを何度もラップしないようにロジックを整理するか、必要に応じて LazyCollection::wrap を利用する |
参考リンク
