Laravel Collection Public API: where

where($key, $operator, $value = null)

The where method allows developers to filter a collection given a key value pair. It filters the collection's items by checking that the given $key has some value equal to the provided $value. An argument can be supplied for the $operator parameter to control how the method internally compares the given key against the value. The where method will return a new Collection instance containing all the items the match the given criteria. The original collection instance will not be modified in any way.

The following code example shows the basic usage of the where method:

 1<?php
 2 
 3use Illuminate\Support\Collection;
 4 
 5// Create a new collection.
 6$collection = new Collection([
 7    [
 8        'genus' => 'Canis',
 9        'name'  => 'tundra wolf',
10        'age'   => '2'
11    ],
12    [
13        'genus' => 'Canis',
14        'name'  => 'arctic wolf',
15        'age'   => 4
16    ],
17    [
18        'genus' => 'Cucumis',
19        'name'  => 'cucumber',
20        'age'   => 2
21    ]
22]);
23 
24// Get all animals with the genus 'Canis'
25$animals = $collection->where('genus', 'Canis');

After the above code has executed, the $animals variable will be an instance of Collection and contain a value similar to the following output:

 1Illuminate\Support\Collection {#478
 2  #items: array:2 [
 3    0 => array:3 [
 4      "genus" => "Canis"
 5      "name" => "tundra wolf"
 6      "age" => "2"
 7    ]
 8    1 => array:3 [
 9      "genus" => "Canis"
10      "name" => "arctic wolf"
11      "age" => 4
12    ]
13  ]
14}

An observant reader will notice that the where method was used with only two parameters used. When the where method is called with only two parameters, such as in where('genus', 'Canis'), the $operator parameter will internally be set to =. This allows the method to maintain backwards compatibility with older versions of the Collection class.

The where method supports the following operators:

Each item in the previous collection contains an age property. Some of these ages are stored as strings, and some are stored as integers. This will be sufficient to show the differences between the equality operators and how they are affected by type comparisons.

1<?php
2 
3// ...
4 
5$typeComparisonResults = $collection->where('age', '===', 2);

After the above code has executed, the $typeComparisonResults collection will only contain one item: the cucumber. This is because the cucumber's age is represented as an integer, and the value 2 was passed into the where method as an integer. If the value 2 was passed as a string the only value returned would have been the tundra wolf.

In Laravel versions 5.2 and below, similar functionality can be achieved using the filter method (the methods demonstrated below are still relevant for Laravel 5.3, however). The following example demonstrates how to use comparison operators with the filter method:

1<?php
2 
3// ...
4 
5// Get all items where the age is
6// greater than or equal to 4.
7$filteredResults = $collection->filter(function ($item) {
8    return data_get($item, 'age') >= 4;
9});

∎