Skip to content

Commit

Permalink
Document missing Collection methods
Browse files Browse the repository at this point in the history
  • Loading branch information
@paulofreitas
paulofreitas committed Oct 1, 2017
1 parent 79a361b commit ceaf4b1
Show file tree
Hide file tree
Showing 2 changed files with 267 additions and 0 deletions.
258 changes: 258 additions & 0 deletions collections.md
View file
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
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

0 comments on commit ceaf4b1

Please sign in to comment.