Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[5.5] Document missing Collection methods #3706

Merged
merged 1 commit into from
Oct 2, 2017
Merged

[5.5] Document missing Collection methods #3706

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
258 changes: 258 additions & 0 deletions collections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

- [Introduction](#introduction)
- [Creating Collections](#creating-collections)
- [Extending Collections](#extending-collections)
- [Available Methods](#available-methods)
- [Higher Order Messages](#higher-order-messages)

Expand All @@ -27,8 +28,33 @@ As mentioned above, the `collect` helper returns a new `Illuminate\Support\Colle

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

Of course, you may also use the `Collection` class constructor or even the static `make()` method:

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

$collection = Collection::make([1, 2, 3]);

> {tip} The results of [Eloquent](/docs/{{version}}/eloquent) queries are always returned as `Collection` instances.

<a name="extending-collections"></a>
### Extending Collections

Collections are macroable, meaning that you can add new methods to the `Collection` class at run time without being required to extend it through inheritance.

For example, here's how we could define a new method on the `Collection` called `mean` that is only an alias to the `average` method:

Collection::macro('mean', function ($callback = null) {
return $this->average($callback);
});

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

$mean = $collection->mean();

// 2

Typically, you should declare your collection's macros in a [service provider](/docs/{{version}}/providers).

<a name="available-methods"></a>
## Available Methods

Expand All @@ -53,13 +79,18 @@ For the remainder of this documentation, we'll discuss each method available on
[chunk](#method-chunk)
[collapse](#method-collapse)
[combine](#method-combine)
[concat](#method-concat)
[contains](#method-contains)
[containsStrict](#method-containsstrict)
[count](#method-count)
[crossJoin](#method-crossjoin)
[dd](#method-dd)
[diff](#method-diff)
[diffAssoc](#method-diffassoc)
[diffKeys](#method-diffkeys)
[dump](#method-dump)
[each](#method-each)
[eachSpread](#method-eachspread)
[every](#method-every)
[except](#method-except)
[filter](#method-filter)
Expand All @@ -80,7 +111,12 @@ For the remainder of this documentation, we'll discuss each method available on
[keyBy](#method-keyby)
[keys](#method-keys)
[last](#method-last)
[macro](#method-macro)
[make](#method-make)
[map](#method-map)
[mapInto](#method-mapinto)
[mapSpread](#method-mapspread)
[mapToGroups](#method-maptogroups)
[mapWithKeys](#method-mapwithkeys)
[max](#method-max)
[median](#method-median)
Expand Down Expand Up @@ -121,6 +157,7 @@ For the remainder of this documentation, we'll discuss each method available on
[union](#method-union)
[unique](#method-unique)
[uniqueStrict](#method-uniquestrict)
[unless](#method-unless)
[unwrap](#method-unwrap)
[values](#method-values)
[when](#method-when)
Expand Down Expand Up @@ -224,6 +261,19 @@ The `combine` method combines the keys of the collection with the values of anot

// ['name' => 'George', 'age' => 29]

<a name="method-concat"></a>
#### `concat()` {#collection-method}

The `concat` method appends the given `array` or collection values into the end of the collection, ignoring any existing keys in the given items:

$collection = collect(['John Doe']);

$concatenated = $collection->concat(['Jane Doe'])->concat(['name' => 'Johnny Doe']);

$concatenated->all();

// ['John Doe', 'Jane Doe', 'Johnny Doe']

<a name="method-contains"></a>
#### `contains()` {#collection-method}

Expand Down Expand Up @@ -278,6 +328,63 @@ The `count` method returns the total number of items in the collection:

// 4

<a name="method-crossjoin"></a>
#### `crossJoin()` {#collection-method}

The `crossJoin` method cross joins the collection's values among the given arrays or collections, returning a Cartesian product with all possible permutations:

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

$matrix = $collection->crossJoin(['a', 'b']);

$matrix->all();

/*
[
[1, 'a'],
[1, 'b'],
[2, 'a'],
[2, 'b'],
]
*/

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

$matrix = $collection->crossJoin(['a', 'b'], ['I', 'II']);

$matrix->all();

/*
[
[1, 'a', 'I'],
[1, 'a', 'II'],
[1, 'b', 'I'],
[1, 'b', 'II'],
[2, 'a', 'I'],
[2, 'a', 'II'],
[2, 'b', 'I'],
[2, 'b', 'II'],
]
*/

<a name="method-dd"></a>
#### `dd()` {#collection-method}

The `dd` method dumps the given collection's items and ends execution of the script:

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dd();

/*
array:2 [
0 => "John Doe"
1 => "Jane Doe"
]
*/

If you do not want to end the script execution, use the [`dump`](#method-dump) method instead.

<a name="method-diff"></a>
#### `diff()` {#collection-method}

Expand Down Expand Up @@ -337,6 +444,26 @@ The `diffKeys` method compares the collection against another collection or a pl

// ['one' => 10, 'three' => 30, 'five' => 50]

<a name="method-dump"></a>
#### `dump()` {#collection-method}

The `dump` method dumps the given collection's items:

$collection = collect(['John Doe', 'Jane Doe']);

$collection->dump();

/*
Collection {
#items: array:2 [
0 => "John Doe"
1 => "Jane Doe"
]
}
*/

If you also want to end the script execution after dumping, use the [`dd`](#method-dd) method instead.

<a name="method-each"></a>
#### `each()` {#collection-method}

Expand All @@ -354,6 +481,25 @@ If you would like to stop iterating through the items, you may return `false` fr
}
});

<a name="method-eachspread"></a>
#### `eachSpread()` {#collection-method}

The `eachSpread` method iterates over the collection's items passing each nested item value into the given callback:

$collection = collect([['John Doe', 35], ['Jane Doe', 33]]);

$collection->eachSpread(function ($name, $age) {
//
});

You may stop iterating through the items by returning `false` from your callback:

$collection->eachSpread(function ($name, $age) {
if (/* some condition */) {
return false;
}
});

<a name="method-every"></a>
#### `every()` {#collection-method}

Expand Down Expand Up @@ -741,6 +887,16 @@ You may also call the `last` method with no arguments to get the last element in

// 4

<a name="method-macro"></a>
#### `macro()` {#collection-method}

The static `macro` method allows you to add methods to the `Collection` class at run time. Refer to the [Extending Collections](#extending-collections) section for more information.

<a name="method-make"></a>
#### `make()` {#collection-method}

The static `make` method creates a new collection instance. See the [Creating Collections](#creating-collections) section.

<a name="method-map"></a>
#### `map()` {#collection-method}

Expand All @@ -758,6 +914,81 @@ The `map` method iterates through the collection and passes each value to the gi

> {note} Like most other collection methods, `map` returns a new collection instance; it does not modify the collection it is called on. If you want to transform the original collection, use the [`transform`](#method-transform) method.

<a name="method-mapinto"></a>
#### `mapInto()` {#collection-method}

The `mapInto()` method iterates over the collection passing each value to the given class:

class Currency
{
function __construct(string $code)
{
$this->code = $code;
}
}

$collection = collect(['USD', 'EUR', 'GBP']);

$currencies = $collection->mapInto(Currency::class);

$currencies->all();

// [Currency('USD'), Currency('EUR'), Currency('GBP')]

<a name="method-mapspread"></a>
#### `mapSpread()` {#collection-method}

The `mapSpread` method iterates over the collection's items passing each nested item value into the given callback. The callback is free to modify the item and return it, thus forming a new collection of modified items:

$collection = collect([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);

$chunks = $collection->chunk(2);

$sequence = $chunks->mapSpread(function ($odd, $even) {
return $odd + $even;
});

$sequence->all();

// [1, 5, 9, 13, 17]

<a name="method-maptogroups"></a>
#### `mapToGroups()` {#collection-method}

The `mapToGroups` method groups the collection's items by the given callback. The callback should return an associative array containing a single key / value pair, thus forming a new collection of grouped values:

$collection = collect([
[
'name' => 'John Doe',
'department' => 'Sales',
],
[
'name' => 'Jane Doe',
'department' => 'Sales',
],
[
'name' => 'Johnny Doe',
'department' => 'Marketing',
]
]);

$grouped = $collection->mapToGroups(function ($item, $key) {
return [$item['department'] => $item['name']];
});

$grouped->toArray();

/*
[
'Sales' => ['John Doe', 'Jane Doe'],
'Marketing' => ['Johhny Doe'],
]
*/

$grouped->get('Sales')->all();

// ['John Doe', 'Jane Doe']

<a name="method-mapwithkeys"></a>
#### `mapWithKeys()` {#collection-method}

Expand Down Expand Up @@ -1531,6 +1762,27 @@ The `unique` method uses "loose" comparisons when checking item values, meaning

This method has the same signature as the [`unique`](#method-unique) method; however, all values are compared using "strict" comparisons.

<a name="method-unless"></a>
#### `unless()` {#collection-method}

The `unless` method will execute the given callback unless the first argument given to the method evaluates to `true`:

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

$collection->unless(true, function ($collection) {
return $collection->push(4);
});

$collection->unless(false, function ($collection) {
return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 5]

For the inverse of `unless`, see the [`when`](#method-when) method.

<a name="method-unwrap"></a>
#### `unwrap()` {#collection-method}

Expand Down Expand Up @@ -1580,10 +1832,16 @@ The `when` method will execute the given callback when the first argument given
return $collection->push(4);
});

$collection->when(false, function ($collection) {
return $collection->push(5);
});

$collection->all();

// [1, 2, 3, 4]

For the inverse of `when`, see the [`unless`](#method-unless) method.

<a name="method-where"></a>
#### `where()` {#collection-method}

Expand Down
9 changes: 9 additions & 0 deletions eloquent-collections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,12 +56,17 @@ All Eloquent collections extend the base [Laravel collection](/docs/{{version}}/
[chunk](/docs/{{version}}/collections#method-chunk)
[collapse](/docs/{{version}}/collections#method-collapse)
[combine](/docs/{{version}}/collections#method-combine)
[concat](/docs/{{version}}/collections#method-concat)
[contains](/docs/{{version}}/collections#method-contains)
[containsStrict](/docs/{{version}}/collections#method-containsstrict)
[count](/docs/{{version}}/collections#method-count)
[crossJoin](/docs/{{version}}/collections#method-crossjoin)
[dd](/docs/{{version}}/collections#method-dd)
[diff](/docs/{{version}}/collections#method-diff)
[diffKeys](/docs/{{version}}/collections#method-diffkeys)
[dump](/docs/{{version}}/collections#method-dump)
[each](/docs/{{version}}/collections#method-each)
[eachSpread](/docs/{{version}}/collections#method-eachspread)
[every](/docs/{{version}}/collections#method-every)
[except](/docs/{{version}}/collections#method-except)
[filter](/docs/{{version}}/collections#method-filter)
Expand All @@ -82,6 +87,9 @@ All Eloquent collections extend the base [Laravel collection](/docs/{{version}}/
[keys](/docs/{{version}}/collections#method-keys)
[last](/docs/{{version}}/collections#method-last)
[map](/docs/{{version}}/collections#method-map)
[mapInto](/docs/{{version}}/collections#method-mapinto)
[mapSpread](/docs/{{version}}/collections#method-mapspread)
[mapToGroups](/docs/{{version}}/collections#method-maptogroups)
[mapWithKeys](/docs/{{version}}/collections#method-mapwithkeys)
[max](/docs/{{version}}/collections#method-max)
[median](/docs/{{version}}/collections#method-median)
Expand Down Expand Up @@ -121,6 +129,7 @@ All Eloquent collections extend the base [Laravel collection](/docs/{{version}}/
[union](/docs/{{version}}/collections#method-union)
[unique](/docs/{{version}}/collections#method-unique)
[uniqueStrict](/docs/{{version}}/collections#method-uniquestrict)
[unless](/docs/{{version}}/collections#method-unless)
[values](/docs/{{version}}/collections#method-values)
[when](/docs/{{version}}/collections#method-when)
[where](/docs/{{version}}/collections#method-where)
Expand Down