最近Laravelを使い始めたんだけど、コレクション(Collection)ってどんなことが出来るの?
配列(Array)ではなくてLaravelのコレクション(Collection)を使うメリットはあるの?
こういった悩みの解決のタネとなるCollectionの使用例を紹介していきます!
- Laravelで使用できるCollectionのメソッド
- Collectionの各メソッドの使い方・使用例
Laravelのコレクション (Collection) は、配列データを扱いやすくするための便利なクラスです。配列に様々なメソッドが追加されたようなもので、データの検索・変換・集計などを簡潔に書けるようになります。
本記事では、Laravel初心者の方に向けて、コレクションでよく使われるメソッド30個をカテゴリー別に紹介します。各メソッドの使い方や引数の型、具体的なコード例を示しながら分かりやすく解説します。
また、Modelからデータ取得した際にreturnされるのはCollection型をベースとしているため、コレクションの使い方を把握しておくと効率的に開発へ取り組むことが出来ます。
取得・操作系メソッド
all()
:コレクションを配列にしたい
allメソッドはコレクションを配列に変換します。引数はなく、返り値は配列になります。コレクションオブジェクトから生のPHP配列が欲しい場合に使用します。
$collection = collect([1, 2, 3]);
$array = $collection->all();
// $array は [1, 2, 3] という配列
上記のようにall()
呼ぶと、コレクション内部のデータが配列として取り出せます。これはLaravelのコレクション独自のオブジェクトではなく、通常のPHP配列になります。
get()
:指定したキーに対応する値を取得したい
get
メソッドは、指定したキーに対応する要素を取得します。引数には取得したい要素のキーを指定し、任意でデフォルト値も指定できます(キーが存在しない場合に返す値)。返り値は該当する要素の値になります。
- 第1引数: int|string 取得する要素のキー
- 第2引数 (オプション): 任意の型 キーが存在しない場合に返すデフォルト値
$collection = collect(['apple' => 150, 'banana' => 300]);
// キー'banana'の値を取得
$price = $collection->get('banana');
// $price は 300
// 存在しないキーの場合、デフォルト値を指定
$unknown = $collection->get('orange', 0);
// $unknown は 0 (キー'orange'がないためデフォルト値)
上記例では、'banana'
というキーに対応する値300
を取得しています。また、存在しないキー'orange'
を指定した場合、第二引数で指定したデフォルト値0
が返されています。
first()
:最初の要素を取得したい
first
メソッドは、コレクションの最初の要素を取得します。基本的に引数は不要ですが、オプションでコールバック関数とデフォルト値を渡すこともできます。返り値は最初の要素の値です(コレクションが空の場合はデフォルト値を返します)。
- 第1引数 (オプション): callable 各要素に対する条件を判定するコールバック関数
- 第2引数 (オプション): 任意の型 コレクションが空の場合に返すデフォルト値
$collection = collect([10, 20, 30]);
$value = $collection->first();
// $value は 10
// コールバック関数で条件を指定(例: 20より大きい最初の要素)
$value2 = $collection->first(function($item) {
return $item > 20;
});
// $value2 は 30 (最初の要素10は条件に合わず、20も条件に合わないため30が取得される)
first()
はシンプルに最初の要素を返すので、上記の例では10
が取得できます。また、コールバック関数を渡すと、その条件を満たす最初の要素が返ります。例えば$item > 20
という条件では、20を超える値のうち最初に見つかった30
が返されています。コレクションが空の場合や条件に合致する要素がない場合には、指定したデフォルト値(指定しなければnull
)が返されます。
last()
:最後の要素を取得したい
last
メソッドはその名の通り、コレクションの最後の要素を取得します。使い方や引数はfirst
メソッドとほぼ同様で、オプションでコールバック関数とデフォルト値を指定できます。返り値は最後の要素の値です。
$collection = collect([10, 20, 30]);
$value = $collection->last();
// $value は 30
// コールバック関数で条件を指定(例: 15より小さい最後の要素)
$value2 = $collection->last(function($item) {
return $item < 15;
});
// $value2 は 10 (15未満の要素は10のみで、それが最後でもあるため)
上記例では、last()
で最後の値30
を取得し、コールバック関数を指定した例では「15より小さい最後の要素」として10
を取得しています。first
と同様、条件に一致する要素がない場合やコレクションが空の場合はデフォルト値を返します。
take()
:先頭から指定した数の分だけ要素を取得したい
take
メソッドは、先頭から指定した件数分の要素を取得します。正の数を渡すと先頭からその数だけ、負の数を渡すと末尾からその数だけの要素を取り出します。返り値は取り出した要素からなる新しいコレクションです。
- 第1引数: int 取得する件数(正なら先頭から、負なら末尾から)
$collection = collect([1, 2, 3, 4, 5]);
$firstThree = $collection->take(3);
$lastTwo = $collection->take(-2);
// $firstThree は Collection([1, 2, 3])
// $lastTwo は Collection([4, 5])
上記の例では、take(3)
によって最初の3要素[1, 2, 3]
を取得し、take(-2)
によって最後の2要素[4, 5]
を取得しています。それぞれ新しいコレクションとして返ってくるため、元のコレクションは変更されません。
each()
:各要素に対して処理を行いたい
each
メソッドは、コレクションの各要素に対して繰り返し処理を行うためのメソッドです。引数に各要素を処理するためのコールバック関数を取ります。**返り値は元のコレクション(変更済みの場合は変更後のコレクション)**です。主に副作用のある処理(ログ出力や合計の計算など)に利用します。
- 第1引数: callable 各要素を処理するコールバック関数(引数に値とキーを取ります)
$collection = collect(['a', 'b', 'c']);
$collection->each(function($item, $key) {
echo "{$key}:{$item}\n";
});
// 出力:
// 0:a
// 1:b
// 2:c
上記では、コレクション['a','b','c']
の各要素をecho
で出力する処理をeach
メソッドで行っています。each
に渡すコールバック関数には、各要素の値とキー(インデックス)が渡されます。each
は元のコレクション自体を返すため、メソッドチェーンの途中に挟んでデバッグしたり、処理を行ったあと引き続き別のメソッドを呼ぶ、といった使い方も可能です(コレクションの内容自体を変換したい場合は後述するmap
やfilter
を使用してください)。
フィルタリング・検索系メソッド
filter()
:条件に一致する要素だけ抽出したい
filter
メソッドは、指定した条件に一致する要素だけを抽出して新しいコレクションを返します。引数には判定用のコールバック関数を渡し、その関数がtrue
を返した要素だけが残ります。返り値は抽出後の新しいコレクションです。
- 第1引数: callable 各要素を評価するコールバック関数(引数に値とキーを取り、真偽値を返す)
$collection = collect([1, 2, 3, 4]);
$even = $collection->filter(function($value, $key) {
return $value % 2 === 0;
});
// $even は Collection([1 => 2, 3 => 4])
上記の例では、filter
に渡したコールバック関数内で「値が偶数か」をチェックしています。結果として偶数である2
と4
だけが残り、新しいコレクション[2, 4]
(キーは元のコレクションのインデックス1と3のまま)となります。元のキーが維持される点に注意してください。必要に応じて、結果を->values()
で呼び出してキーを0からの連番に振り直すこともできます。
$evenReindexed = $even->values();
// $evenReindexed は Collection([0 => 2, 1 => 4]) となりキーがリセットされる
where()
:連想配列やオブジェクトから条件に一致する要素だけ抽出したい
where
メソッドは、コレクション内の連想配列やオブジェクトから特定キーの値が指定した条件に合致する要素を抽出します。基本的に「キーと値が一致する要素」を取り出す用途でよく使われます。返り値は条件を満たした要素の新しいコレクションです。
- 第1引数: string 調べるキー名
- 第2引数: mixed 比較する値(※第3引数を省略した場合は「=(等しい)」で比較)
- 第3引数 (オプション): string 演算子(
'='
,'>'
,'>='
など)※省略時は'='
(厳密比較ではなく緩やかな等価比較)
$users = collect([
['name' => 'John', 'age' => 30],
['name' => 'Jane', 'age' => 25],
['name' => 'Doe', 'age' => 35],
]);
// 年齢が30以上の要素を抽出
$filtered = $users->where('age', '>=', 30);
// $filtered は Collection([ ['name' => 'John', 'age' => 30], ['name' => 'Doe', 'age' => 35] ])
この例では、各要素が持つage
キーの値に注目し、>= 30
という条件に合致する要素(JohnとDoe)だけを含むコレクションを取得しています。where
メソッドは内部的にはfilter
を利用していますが、特定のキーでの単純な比較であればwhere
を使う方が簡潔です。
演算子を省略した場合(引数2つのみの場合)は「キーの値が指定の値に等しい」要素を返します。また、厳密な比較(型も含めて比較)をしたい場合は、whereStrict()
というメソッドも用意されています。
whereIn()
:配列に含まれる値の要素を抽出したい
whereIn
メソッドは、指定したキーの値が、あるリスト(配列)の中に含まれている要素を抽出します。例えば「statusが特定の複数の値のいずれかに合致するレコードを取得したい」といった場合に便利です。返り値は条件を満たした新しいコレクションです。
- 第1引数: string 調べるキー名
- 第2引数: array 許容する値の配列
$users = collect([
['name' => 'John', 'age' => 30],
['name' => 'Jane', 'age' => 25],
['name' => 'Doe', 'age' => 35],
]);
// 年齢が25歳または35歳の要素を抽出
$filtered = $users->whereIn('age', [25, 35]);
// $filtered は Collection([ ['name' => 'Jane', 'age' => 25], ['name' => 'Doe', 'age' => 35] ])
上記では、age
が25
または35
のユーザーを抽出しています。このようにwhereIn
に値のリストを渡すことで、「キーの値がリストの中に含まれるか?」でフィルタリングできます。反対に「指定のリストに含まれないもの」を抽出するwhereNotIn
メソッドもあります。
contains()
:特定の値や条件に合致する要素が存在するか
contains
メソッドは、コレクションに特定の値や条件に合致する要素が存在するかどうかを確認します。該当するものがあればtrue
、なければfalse
を返すブール値の結果になります。引数の与え方によって挙動が変わり、以下の使い方が可能です。
- 値を直接指定: その値がコレクション内に存在するかを判定
- キーと値を指定: コレクション内に、指定したキーにその値を持つ要素が存在するかを判定
- コールバック関数を指定: コールバックが
true
を返すような要素が存在するかを判定
$numbers = collect([1, 2, 3]);
$hasTwo = $numbers->contains(2);
// $hasTwo は true (値2が存在する)
$users = collect([
['name' => 'John', 'age' => 30],
['name' => 'Jane', 'age' => 25],
]);
$hasDoe = $users->contains('name', 'Doe');
// $hasDoe は false (nameが'Doe'の要素は存在しない)
// コールバック関数で条件指定: 年齢が30のユーザーがいるか
$hasAge30 = $users->contains(function($user) {
return $user['age'] === 30;
});
// $hasAge30 は true (Johnの年齢が30)
1つ目の例では、数値2
がコレクションに含まれるためtrue
が返っています。2つ目の例では、name
キーがDoe
である要素は存在しないためfalse
になります。3つ目では、コールバック内で「age
が30かどうか」をチェックし、その条件に合う要素(John)があるためtrue
となっています。
unique()
:重複する値を取り除いてユニークな要素だけ残す
unique
メソッドは、コレクション内の重複する値を取り除いてユニークな要素だけを残す新しいコレクションを返します。重複の判定は値全体で行われますが、連想配列やオブジェクトの場合は特定のキーを指定してそのキーの値が重複しているかどうかで判定することもできます。返り値は重複が除かれた新しいコレクションです。
- 第1引数 (オプション): string|callable ユニーク判定に使用するキー名、またはコールバック関数(省略時は要素そのものを比較)
$numbers = collect([1, 2, 2, 3, 1]);
$uniqueNumbers = $numbers->unique();
// $uniqueNumbers は Collection([0 => 1, 1 => 2, 3 => 3])
$users = collect([
['id' => 1, 'name' => 'Alice'],
['id' => 2, 'name' => 'Bob'],
['id' => 3, 'name' => 'Alice'],
]);
$uniqueNames = $users->unique('name');
// $uniqueNames は Collection([ ['id' => 1, 'name' => 'Alice'], ['id' => 2, 'name' => 'Bob'] ])
最初の例では、[1,2,2,3,1]
というコレクションから重複する数値を除いて[1,2,3]
という結果を得ています。最初に出現した値が優先して残り、後の重複は取り除かれます(そのため結果のキーは元の0,1,3のままになっています)。2つ目の例では、name
キーを指定して重複チェックを行い、'Alice'
という名前が重複していたので最初のAliceだけを残し、それ以降のAliceは除外されています(結果としてAliceとBobの2件だけ残る)。こちらも元の順序を保ち、重複する要素は除去されます。
変換・マッピング系メソッド
map()
:各要素を別の値に変更したい
map
メソッドは、コレクションの各要素を別の値に変換した新しいコレクションを返します。引数には変換処理を行うコールバック関数を渡し、その関数の返り値が新しいコレクションの要素となります。返り値は変換後の要素からなる新しいコレクションです。
- 第1引数: callable 各要素を変換するコールバック関数(引数に値とキーを取り、任意の値を返す)
$numbers = collect([1, 2, 3]);
$double = $numbers->map(function($value, $key) {
return $value * 2;
});
// $double は Collection([2, 4, 6])
上記では、数値のコレクション[1,2,3]
に対してmap
を適用し、各値を2倍に変換しています。結果は[2,4,6]
となり、新しいコレクションとして得られます。map
では元のコレクションは変更されず、返り値として変換後のコレクションが返ってくる点に注意してください。
別の例として、オブジェクトや連想配列のコレクションにmap
を使って特定のプロパティだけを取り出したり、フォーマットを変更することもできます。例えばユーザーのコレクションから名前だけのリストを作る場合などに利用できます(その用途では後述のpluck
メソッドの方が簡単です)。
pluck()
:指定したキーの値だけを抜き出したい
pluck
メソッドは、コレクション内の各要素から指定したキーの値だけを抜き出したコレクションを返すメソッドです。多次元配列やオブジェクトの配列から特定の項目の一覧を取得したい場合に便利です。返り値は抽出した値のコレクションです。
- 第1引数: string 抜き出したいキー名(ドット区切りでネストしたキーも指定可能)
- 第2引数 (オプション): string 抜き出した値に対して使用するキー名(省略時は連番のキー or 元のキーがそのまま使用される)
$users = collect([
['name' => 'John', 'age' => 30],
['name' => 'Jane', 'age' => 25],
['name' => 'Doe', 'age' => 35],
]);
$names = $users->pluck('name');
// $names は Collection(['John', 'Jane', 'Doe'])
この例では、各ユーザーのname
だけを抜き出して、['John','Jane','Doe']
というコレクションを取得しています。pluck('キー名')
を使うことで、ループを書かずとも特定の列の値一覧を簡単に取り出すことができます。
また、第2引数を指定すると、結果のコレクションのキーを好きな値に設定できます。例えば$users->pluck('age', 'name')
とすると、name
をキー、age
を値とする連想コレクション(例: ['John' => 30, 'Jane' => 25, ...]
)を取得できます。このようにpluck
はキーと値のペアで新しいコレクションを組み立てる用途にも使えます。
flatMap()
:各要素を別の値に変更して、1次元コレクションにしたい
flatMap
メソッドは、map
による変換とフラット化 (flatten) を同時に行うメソッドです。各要素に対する変換処理で配列やコレクションを返す場合に、それを一段フラットにしたコレクションを得ることができます。返り値はフラット化された新しいコレクションです。
- 第1引数: callable 各要素を変換するコールバック関数(返す値は配列もしくはコレクション)
$numbers = collect([1, 2, 3]);
$mapped = $numbers->map(function($value) {
return [$value, $value * 10];
});
$flatMapped = $numbers->flatMap(function($value) {
return [$value, $value * 10];
});
// $mapped は Collection([[1, 10], [2, 20], [3, 30]])
// $flatMapped は Collection([1, 10, 2, 20, 3, 30])
上記では、map
とflatMap
の違いを示しています。コールバック関数内で各値から[$value, $value * 10]
という配列を返しています。map
の場合、結果は配列のコレクション(ネストした構造)になりますが、flatMap
を使うとネストを一段解消し、返された配列の要素がフラットに一つのコレクションにまとめられます。つまりflatMap
は「各要素を複数の要素にマッピングする」ような処理に便利で、1対多の変換をシンプルに記述できます。
flatten()
:多次元コレクションから1次元コレクションにしたい
flatten
メソッドは、多次元のコレクション(ネストした配列やコレクション)を平坦化して1次元のコレクションにするメソッドです。ネストの深さを指定することもできます。返り値は平坦化された新しいコレクションです。
- 第1引数 (オプション): int 平坦化する深さ(省略時はすべて平坦化)
$nested = collect([ [1, 2], [3, 4], 5 ]);
$flatAll = $nested->flatten();
// $flatAll は Collection([1, 2, 3, 4, 5])
上記では、二次元のコレクション[[1,2],[3,4],5]
をflatten
することで、[1,2,3,4,5]
という一次元のコレクションを得ています。デフォルトではネストをすべて平坦化しますが、例えば3次元以上の構造で一段階だけ平坦化したい場合(深さを指定したい場合)は、flatten(1)
のように深さを渡すこともできます。
$multi = collect([1, [2, [3, 4]], 5]);
$flatOne = $multi->flatten(1);
// $flatOne は Collection([1, 2, [3, 4], 5])
この例でflatten(1)
とすると、最外層のネストだけが解消され、[3,4]
というネストは残ったままになります。
groupBy()
:指定したキーや条件でグループ分けしたい
groupBy
メソッドは、コレクションの要素を指定したキーや条件でグループ分けするメソッドです。例えば「ユーザを所属チームごとにグループ化する」「レコードを日付ごとにまとめる」といった用途に使えます。返り値はグループ化された新しいコレクションで、キーがグループのキー値、値がそのグループに属する要素のサブコレクションとなります。
- 第1引数: string|callable グループ化のキーとなる項目名、またはグループを決定するためのコールバック関数
$members = collect([
['name' => 'Alice', 'team' => 'red'],
['name' => 'Bob', 'team' => 'blue'],
['name' => 'Carol', 'team' => 'red'],
]);
$grouped = $members->groupBy('team');
// $grouped は Collection([
// "red" => Collection([ ['name'=>'Alice','team'=>'red'], ['name'=>'Carol','team'=>'red'] ]),
// "blue" => Collection([ ['name'=>'Bob','team'=>'blue'] ])
// ])
上記では、team
キーを基準にメンバーをグループ化しています。結果は、キー"red"
に赤チームのメンバーコレクション、キー"blue"
に青チームのメンバーコレクション、という構造になります。このようにしておくと、例えば$grouped['red']
で赤チームのメンバー一覧にアクセスする、といった使い方ができます。
コールバック関数を渡して、より柔軟なグループ分けをすることも可能です。例えば、点数のコレクションを10点刻みにグループ化したり、日付から年月を切り出して同じ年月のデータでグループにする、などの応用ができます。
$scores = collect([65, 72, 90, 45, 81]);
$groupedScores = $scores->groupBy(function($score) {
return intval($score / 10) * 10; // 10の位でグループ化
});
// $groupedScores は Collection([
// 40 => [45],
// 60 => [65],
// 70 => [72],
// 80 => [81],
// 90 => [90]
// ])
この例ではスコアを10の位でグループ化し、たとえば80
キーには81
点が属しています(80点台グループ)。
ソート・並び替え系メソッド
sort()
:要素を昇順に並び替えたい
sort
メソッドは、コレクションの要素を昇順に並び替えます。引数を省略すると、数値なら値の昇順、文字列ならアルファベット順にソートします。オプションでユーザー定義の比較関数を渡して独自の順序付けをすることもできます。返り値はソート後の新しいコレクションです(元のコレクションは変更されません)。
- 第1引数 (オプション): callable 比較に使用する関数(省略時はデフォルトの昇順比較)
$numbers = collect([3, 1, 4, 2]);
$sorted = $numbers->sort();
// $sorted は Collection([1, 2, 3, 4])
上記例では、[3,1,4,2]
というコレクションをソートし、[1,2,3,4]
に並び替えています。sort()
はデフォルトで各要素の値自体を比較して昇順に並べます。
$sortedReindexed = $numbers->sort()->values();
// $sortedReindexed は Collection([0 => 1, 1 => 2, 2 => 3, 3 => 4])
sortBy()
:各要素が持つキーや計算結果に基づいて昇順に並び替えたい
sortBy
メソッドは、コレクションの各要素が持つキーや計算結果に基づいて昇順に並び替えるメソッドです。主に連想配列やオブジェクトのコレクションで、「特定のフィールドでソートしたい」という場合に使われます。返り値は並べ替え後の新しいコレクションです。
- 第1引数: string|callable 並び替えの基準とするキー名、または各要素から比較に使う値を取り出すコールバック関数
- 第2引数 (オプション): int ソートフラグ(PHPのsort関数に準拠、基本省略可)
$users = collect([
['id' => 1, 'name' => 'John', 'age' => 30],
['id' => 2, 'name' => 'Jane', 'age' => 25],
['id' => 3, 'name' => 'Doe', 'age' => 35],
]);
$sortedByAge = $users->sortBy('age');
// $sortedByAge は Collection([
// ['id'=>2, 'name'=>'Jane', 'age'=>25],
// ['id'=>1, 'name'=>'John', 'age'=>30],
// ['id'=>3, 'name'=>'Doe', 'age'=>35]
// ])
この例では、age
の値を基準に昇順ソートを行っています。年齢25のJane、30のJohn、35のDoeの順に並び替えられました。sortBy('キー名')
とするだけで、そのキーの値によるソートが可能です。
また、コールバック関数を渡して、複雑な計算結果に基づくソートをすることもできます。例えば、文字列の長さでソートしたり、日時データをフォーマットして比較したりする場合などです。
$words = collect(['apple', 'banana', 'kiwi']);
$sortedByLength = $words->sortBy(function($word) {
return strlen($word);
});
// $sortedByLength は Collection(['kiwi', 'apple', 'banana'])
// (文字数が短い順: 4文字, 5文字, 6文字)
上記では単語のコレクションを文字数の短い順に並べ替えています。
sortByDesc()
:要素を降順に並び替えたい
sortByDesc
メソッドは、sortBy
の降順バージョンです。使い方・引数はsortBy
と同様ですが、並び順が降順(大きいものが先)になる点が異なります。返り値は降順に並べ替えた新しいコレクションです。
$users = collect([
['id' => 1, 'name' => 'John', 'age' => 30],
['id' => 2, 'name' => 'Jane', 'age' => 25],
['id' => 3, 'name' => 'Doe', 'age' => 35],
]);
$sortedByAgeDesc = $users->sortByDesc('age');
// $sortedByAgeDesc は Collection([
// ['id'=>3, 'name'=>'Doe', 'age'=>35],
// ['id'=>1, 'name'=>'John', 'age'=>30],
// ['id'=>2, 'name'=>'Jane', 'age'=>25]
// ])
年齢順で降順にソートした結果、年齢35のDoe、30のJohn、25のJaneの順になっています。sortByDesc
は内部的にはsortBy
で取得した結果を反転させるような動作ですが、Laravelが用意しているためシンプルに書くことができます。
reverse()
:要素の順序を反転(逆順に)したい
reverse
メソッドは、コレクション内の要素の順序を反転(逆順に)するメソッドです。ソートとは限らず、単に現在の順番を逆にしたいときに使用します。返り値は順序を反転させた新しいコレクションです。
$collection = collect([1, 2, 3]);
$reversed = $collection->reverse();
// $reversed は Collection([3, 2, 1])
上記の例では、[1,2,3]
というコレクションをreverse()
することで[3,2,1]
になっています。reverse()
も他のメソッド同様、元のキーを保持した上で逆順にするため、元が順序キー(0,1,2)であれば結果はキーが反転して2=>1, 1=>2, 0=>3
のようになります。ただ単純に順序を逆にしたリストが欲しい場合は、その後values()
でキーをリセットしてください。
reverse()
は降順ソートとは異なり、現在の並び順そのものをひっくり返すだけなので、一度何らかの基準でソートした後に逆順にしたい場合にも利用できます。例えば、$sorted = $users->sortBy('age'); $descending = $sorted->reverse();
とすればsortByDesc
と同じ結果が得られます。また、何もソートしていない場合は元の挿入順を逆にするので、スタックや履歴データを後ろから辿りたいようなケースでも役立ちます。
shuffle()
: 要素をランダムに並び替えたい(番外編)
※shuffle
メソッドも順序操作の一種で、コレクション内の要素をランダムに並び替える機能があります(引数は不要で、返り値はランダム順に並べ替えた新しいコレクションです)。例えば $randomOrder = $collection->shuffle();
のように使用します。用途に応じて必要であれば活用できます。
集計・統計系メソッド
count()
:要素数を取得したい
count
メソッドは、コレクションの要素数(件数)を取得します。引数はなく、返り値は整数です。配列のcount()
やsizeof()
関数と同様の役割ですが、コレクションオブジェクトに対してメソッドとして呼び出せます。
$collection = collect(['x', 'y', 'z']);
$total = $collection->count();
// $total は 3
上記では、コレクション['x','y','z']
の要素数は3つなので、count()
は3
を返します。単純に件数を得たい場合に使用します。なお、Laravelのコレクションは Countable
インターフェースを実装しているため、PHPの組み込み関数 count($collection)
と呼んでも同じ結果が得られます。
sum()
:数値の合計を取得したい
sum
メソッドは、コレクション内の数値の合計を計算します。数値のコレクションであれば全ての値を加算した結果を返し、連想配列やオブジェクトのコレクションであれば特定のキーを指定してその値の合計を計算することもできます。**返り値は合計値(数値)**です。
- 第1引数 (オプション): string|callable 合計を計算する値を取り出すキー名、またはコールバック(省略時は要素そのものを数値として合計)
$numbers = collect([5, 10, 15]);
$total = $numbers->sum();
// $total は 30
$users = collect([
['name' => 'John', 'score' => 50],
['name' => 'Jane', 'score' => 80],
['name' => 'Doe', 'score' => 70],
]);
$totalScore = $users->sum('score');
// $totalScore は 200
1つ目の例では、5+10+15
の合計である30
が返っています。2つ目の例では、各要素が持つscore
キーの値を合計するためにsum('score')
としています。これにより 50+80+70 = 200
が計算されます。
コールバック関数を渡すことで、例えばオブジェクトのプロパティ同士を掛け合わせた結果の合計を出す、といった柔軟な計算も可能です。しかし、単純な合計であれば上記のようにキー名を指定するだけで十分でしょう。
average()
・avg()
: 数値の平均値を取得したい
average
メソッド(エイリアス: avg
)は、コレクション内の数値の平均値を計算します。sum
同様、数値のコレクションならその平均、連想配列やオブジェクトのコレクションなら特定のキーを指定してその平均値を算出できます。**返り値は平均値(数値)**です。
- 第1引数 (オプション): string|callable 平均を計算する値を取り出すキー名、またはコールバック(省略時は要素そのものを数値として平均算出)
$numbers = collect([5, 10, 15]);
$avg = $numbers->average();
// $avg は 10 (30の合計 / 3件)
$users = collect([
['name' => 'John', 'score' => 50],
['name' => 'Jane', 'score' => 80],
['name' => 'Doe', 'score' => 70],
]);
$avgScore = $users->avg('score');
// $avgScore は 66.666... (200の合計 / 3件)
上記では、最初の例で(5+10+15)/3 = 10
という平均、2つ目の例ではscore
の平均で200/3 ≒ 66.67
が計算されています。avg()
はaverage()
の短縮エイリアスで、どちらを使っても同じ動作をします。
max()
:最大値を取得を取得したい
max
メソッドは、コレクション内の最大値を取得します。数値コレクションであればその中で最も大きい数値を返し、連想配列やオブジェクトの場合はキーを指定してそのキーの最大値を持つ要素を返します(正確にはキーを指定した場合、そのキーの値の最大値を返します)。返り値は最大値です。
- 第1引数 (オプション): string|callable 最大値を比較するキー名、または取得する値を決めるコールバック(省略時は要素そのものを比較)
$numbers = collect([5, 10, 15]);
$maxValue = $numbers->max();
// $maxValue は 15
$users = collect([
['name' => 'John', 'score' => 50],
['name' => 'Jane', 'score' => 80],
['name' => 'Doe', 'score' => 70],
]);
$maxScore = $users->max('score');
// $maxScore は 80
数値のみの例では5,10,15
の中で最大の15
が返っています。users
コレクションの例では、score
キーを基準に最大値を取得しており、最高得点80
を持つJaneのスコア80
が返されます。
min()
:最小値を取得したい
min
メソッドは、max
の逆でコレクション内の最小値を取得します。使い方・引数はmax
と同様です。返り値は最小値です。
$numbers = collect([5, 10, 15]);
$minValue = $numbers->min();
// $minValue は 5
$users = collect([
['name' => 'John', 'score' => 50],
['name' => 'Jane', 'score' => 80],
['name' => 'Doe', 'score' => 70],
]);
$minScore = $users->min('score');
// $minScore は 50
上記例では、それぞれ5
および50
が最小値として取得されています。
結合・分割系メソッド
push()
:末尾に要素を追加したい
push
メソッドは、コレクションの末尾に要素を追加します。引数に追加したい値を渡すと、その値がコレクションの最後に加えられます。返り値はコレクション自身です(追加後のコレクションオブジェクトが返りますが、同じインスタンスです)。このメソッドはコレクションを破壊的に変更する(ミュータブル)点に注意してください。すなわち元のコレクション自体が変化します。
- 第1引数: mixed 追加する値
collection = collect([1, 2, 3]);
$collection->push(4);
上記のコードを実行すると、$collection
には新たに4
が追加され、内容は[1, 2, 3, 4]
となります。push
はコレクション自身を返すので、例えば$collection->push(5)->push(6);
のようにメソッドチェーンで続けて追加することも可能です(この場合最終的に[1,2,3,4,5,6]
になります)。
concat()
:別の配列やコレクションを末尾に連結したい
concat
メソッドは、別の配列やコレクションの要素を現在のコレクションの末尾に連結します。push
が単一要素を追加するのに対し、concat
は複数の要素(配列やコレクション全体)を一度に追加できます。返り値は連結後の新しいコレクションです(元のコレクションは変更されません)。
- 第1引数: array|\Illuminate\Support\Collection 連結する配列またはコレクション
$collection1 = collect([1, 2]);
$collection2 = collect([3, 4]);
$combined = $collection1->concat($collection2);
// $combined は Collection([1, 2, 3, 4])
// $collection1 は元のまま Collection([1, 2])
この例では、$collection1
に$collection2
を連結し、新しいコレクション[1,2,3,4]
を得ています。concat
は非破壊的で、元の$collection1
は変更されないことに注意してください。結果を受け取った$combined
が新しいコレクションとなります。
concat
は連結される側のキーを無視し、単純に末尾に値を追加します。例えば、連想配列同士をconcat
した場合、連結する配列のキーはリセットされて数値インデックスとして追加されます。元のコレクションのキーは維持されますが、新しく加わる要素には新しいキーが付与されるイメージです(そのため、キーも含めてマージしたい場合は後述のmerge
を使う必要があります)。
merge()
:別の配列やコレクションを結合したい
merge
メソッドは、別の配列やコレクションを現在のコレクションと結合します。concat
との違いは、キーを維持・統合する点です。連想配列(キー付き配列)の場合、同じキーが存在すると後から渡した配列の値で上書きされ、異なるキーはそのまま追加されます。数値インデックスの場合は、PHPのarray_merge
と同様に後からの要素が順番に追加されます(キーは再割り当てされます)。返り値はマージ後の新しいコレクションです(元のコレクションは変更されません)。
- 第1引数: array|\Illuminate\Support\Collection マージする配列またはコレクション
$collectionA = collect(['a' => 1, 'b' => 2]);
$collectionB = collect(['b' => 3, 'c' => 4]);
$merged = $collectionA->merge($collectionB);
// $merged は Collection(['a' => 1, 'b' => 3, 'c' => 4])
// $collectionA は元のまま Collection(['a' => 1, 'b' => 2])
この例では、$collectionA
と$collectionB
をマージしています。$collectionA
と$collectionB
の両方に存在するキーb
については、後からの$collectionB
の値3
で上書きされました。キーa
とc
は片方にしかないので、そのまま含まれています。
数値キーの場合も試してみます。
$c1 = collect([1, 2]);
$c2 = collect([3, 4]);
$mergedNums = $c1->merge($c2);
// $mergedNums は Collection([1, 2, 3, 4])
このように、単純に後ろにくっつく点ではconcat
と同じ結果になりますが、merge
は連想キーも扱える点や元のコレクションは変更しない(イミュータブル)点で異なります。逆に、元のキーを保持したまま単純結合したい場合はunion
メソッド(同じキーは無視して追加しない)などもあります。
chunk()
:指定したサイズごとに分割したい
chunk
メソッドは、コレクションを指定したサイズごとの複数の塊(チャンク)に分割します。返されるのは「チャンクごとのコレクション」を要素とする新しいコレクションです。大量のデータを扱う際に、一定サイズずつ処理したい場合などに使用します。
- 第1引数: int チャンク(塊)1つあたりの要素数
$collection = collect([1, 2, 3, 4, 5]);
$chunks = $collection->chunk(2);
// $chunks は Collection([
// Collection([1, 2]),
// Collection([3, 4]),
// Collection([5])
// ])
例では、5つの要素を持つコレクションを2つずつの塊に分割しています。結果は3つのコレクションからなるコレクションで、[1,2]
, [3,4]
, [5]
というグループに分かれました。最後のグループは要素数が不足しますが、そのまま残ります。
チャンク化後の外側のコレクションの各要素は元のコレクションから分割された小さなコレクションです。例えば、上記の$chunks
から最初のチャンクを取り出すには$chunks[0]
とし、その中身([1,2]
)にアクセスできます。
implode()
:要素を文字列として連結したい
implode
メソッドは、コレクション要素を文字列として連結するためのメソッドです。配列のimplode
(PHPのimplode
関数)に似ていますが、コレクションの場合はメソッドとして提供されています。主に文字列のコレクションや、オブジェクト/連想配列コレクションから特定のフィールドを取り出して1つの文字列にまとめたい場合に使います。返り値は連結された文字列です。
- 引数パターン:
(string $glue)
コレクションが文字列の集まりの場合、その間に挟む区切り文字列を指定(string $key, string $glue)
コレクションが連想配列やオブジェクトの場合、取り出したいキー名と区切り文字列を指定
$names = collect(['Alice', 'Bob', 'Charlie']);
$joined = $names->implode(', ');
// $joined は "Alice, Bob, Charlie"
単純な文字列のコレクションに対して、カンマとスペースで連結しています。結果は1つの文字列となります。
連想配列のコレクションに対しては、まず抽出するキーを指定し、その値を繋ぐ形になります。
$users = collect([
['name' => 'Alice', 'age' => 20],
['name' => 'Bob', 'age' => 25],
['name' => 'Carol', 'age' => 22],
]);
$namesList = $users->implode('name', ' & ');
// $namesList は "Alice & Bob & Carol"
この例では、各ユーザーのname
を取り出して「 & 」で繋いでいます。結果として"Alice & Bob & Carol"
という文字列が得られます。
implode
は、ビューにデータを表示する際などに、コレクションの内容を簡潔に区切り文字付きで出力したい場合に役立ちます。
メモ: 単純な条件での絞り込みであれば、後述するwhereメソッドを使うことでより簡潔に書けます。また、条件に合致しない要素だけを残したい場合は、filterの代わりにrejectメソッドを使うこともできます(rejectはfilterの逆で、コールバックがtrueを返した要素を除外します)。