expand_less

Collections

Introduction

The Framework\Support\Collections\Collection class offers a fluent and convenient wrapper for manipulating arrays of data. Take a look at the following code for an example. Here, we use the collect helper to create a new collection instance from an array. We then apply the filter function to remove empty values from each element and finally retrieve the last element: 

                                
                                    

                                        $collection = collect(['taylor', 'abigail', null])->filter()->last();

As demonstrated, the Collection class enables method chaining, allowing you to fluently map and reduce the underlying array. It's important to note that collections are generally immutable. This means that each method call on a collection returns an entirely new Collection instance.

Creating Collections

The collect helper generates a new Framework\Support\Collections\Collection instance for the provided array. Therefore, creating a collection is straightforward: 

                                
                                    

                                        $collection = collect([1,2,3,4,5]);

It's worth noting that the results of ORM queries are consistently returned as Collection instances.

Available Methods

In the subsequent sections of the collection documentation, we will explore each method provided by the Collection class. Keep in mind that all these methods can be chained to seamlessly manipulate the underlying array. Additionally, it's important to note that nearly every method returns a new Collection instance. This feature enables you to maintain the integrity of the original collection whenever required:

all add count filter first get implode isEmpty isNotEmpty keys last map pluck toArray values

all()

The all method returns the underlying array represented by the collection.

add()

The add method adds specified item to the collection.

count()

The count method returns the total number of items in the collection.

filter()

The filter method filters the collection using the given callback, keeping only those items that pass a given truth test.

first()

The first method returns the first element in the collection that passes a given truth test. You may also call the first method with no arguments to get the first element in the collection. If the collection is empty, null is returned.

get()

The get method returns the item at a given key. If the key does not exist, null is returned. You may optionally pass a default value or callback as the second argument.

implode()

The implode method joins items in a collection. Its arguments depend on the type of items in the collection. If the collection contains arrays or objects, you should pass the key of the attributes you wish to join, and the "glue" string you wish to place between the values. 

                                
                                    

                                        $collection = collect([['name' => 'taylor', 'age' => 18], ['name' => 'john', 'age' => 20]]);
                                    

                                    

                                         
                                    

                                    

                                        $collection->implode('name', ', ');

isEmpty()

The isEmpty method returns true if the collection is empty; otherwise, false is returned.

isNotEmpty()

The isNotEmpty method returns true if the collection is not empty; otherwise, false is returned.

keys()

The keys method returns all of the collection's keys.

last()

The last method returns the last element in the collection that passes a given truth test. You may also call the last method with no arguments to get the last element in the collection. If the collection is empty, null is returned.

map()

The map method iterates through the collection and passes each value to the given callback. The callback is free to modify the item and return it, thus forming a new collection of modified items: 

                                
                                    

                                        $collection = collect([1,2,3]);
                                    

                                    

                                         
                                    

                                    

                                        $newCollection = $collection->map(fn($item) => $item * 2);

pluck()

The pluck method retrieves all of the values for a given key. 

                                
                                    

                                        $collection = collect([['name' => 'taylor', 'age' => 18], ['name' => 'john', 'age' => 20]]);
                                    

                                    

                                         
                                    

                                    

                                        $collection->pluck('name');

toArray()

The toArray method converts the collection into a plain PHP array. If the collection's values are ORM models, the models will also be converted to arrays.

values()

The values method returns all the values of the collection.