Laravel Collection Public API: contains

contains($key, $value = null)

The contains method is used to determine if a given $key exists within the collection. Additionally, an option $value can be specified that will be used to check if a given key/value pair exists within the collection. The contains method is incredibly versatile, and each use case will be highlighted below.

The following demonstrates the contains method in its most basic usage:

 1<?php
 2 
 3use Illuminate\Support\Collection;
 4 
 5// Create a new collection instance.
 6$collection = new Collection([
 7    'bear',
 8    'whale',
 9    'chicken',
10    'tardigrade'
11]);
12 
13// true
14$collection->contains('bear');
15 
16// true
17$collection->contains('tardigrade');
18 
19// false
20$collection->contains('dog');

The following demonstrates using the contains method to check if a given key/value pair exists in a collection that contains arrays as items:

 1<?php
 2 
 3use Illuminate\Support\Collection;
 4 
 5// Create a new collection instance.
 6$collection = new Collection([
 7    ['big'     => 'bear'],
 8    ['bigger'  => 'whale'],
 9    ['small'   => 'chicken'],
10    ['smaller' => 'tardigrade']
11]);
12 
13// true
14$collection->contains('big', 'bear');
15 
16// true
17$collection->contains('smaller', 'tardigrade');
18 
19// false
20$collection->contains('smaller', 'paramecium');

The following example shows how the contains method can be used on collections of objects, using a hypothetical User class:

 1<?php
 2 
 3use Illuminate\Support\Collection;
 4 
 5class User
 6{
 7 
 8    /**
 9     * A hypothetical user's first name.
10     *
11     * @var string
12     */
13    public $firstName = '';
14 
15    /**
16     * A hypothetical user's favorite number.
17     *
18     * @var integer
19     */
20    public $favoriteNumber = 0;
21 
22    public function __construct($firstName, $favoriteNumber)
23    {
24        $this->firstName      = $firstName;
25        $this->favoriteNumber = $favoriteNumber;
26    }
27 
28}
29 
30// Create a new collection instance.
31$collection = new Collection([
32    new User('Jane', 7),
33    new User('Sarah', 9),
34    new User('Ben', 2)
35]);
36 
37// true
38$collection->contains('firstName', 'Jane');
39 
40// false
41$collection->contains('firstName', 'Josh');
42 
43// false
44$collection->contains('lastName', 'Jane');
45 
46// true
47$collection->contains('favoriteNumber', 2);

A function can also be supplied as the only argument to the contains method. The following example demonstrates how to determine if there are any user's that have favorite numbers greater than 7:

1<?php
2 
3// true
4$collection->contains(function($key, $value) {
5    return $value->favoriteNumber > 7;
6});

It should be noted that in the above example that the $value will be an instance of the User class. Additionally, truth tests can be as complex as required. The following will determine if there are any favorite numbers between 7 and 9, including 7 and 9:

1<?php
2 
3// true
4$collection->contains(function($key, $value) {
5    return ($value->favoriteNumber >= 7 && $value->favoriteNumber <= 9);
6});

#Considerations of The contains method

The contains method defines two parameters: $key and $value. The $value parameter has a default value of null, however, the two method calls are not the same:

 1<?php
 2 
 3use Illuminate\Support\Collection;
 4 
 5$collection = new Collection([
 6    'first', 'second', 'third'
 7]);
 8 
 9// true
10$collection->contains('third');
11 
12// true
13$collection->contains('third', null);

Even though the two examples return true, the second example is functionally not correct. When explicitly passing null as the second argument, the contains method will always return true:

1<?php
2 
3// true
4$collection->contains('fourth', null);

The above example returns true even though fourth is not in the collection.

∎