From ceaf4b1dd155b6d9d50cb979e54d7dc4f50e1b14 Mon Sep 17 00:00:00 2001
From: Paulo Freitas <me@paulofreitas.me>
Date: Sun, 1 Oct 2017 18:57:06 -0300
Subject: [PATCH] Document missing Collection methods

---
 collections.md          | 258 ++++++++++++++++++++++++++++++++++++++++
 eloquent-collections.md |   9 ++
 2 files changed, 267 insertions(+)

diff --git a/collections.md b/collections.md
index 0d13eb8ee13..5763fac9205 100644
--- a/collections.md
+++ b/collections.md
@@ -2,6 +2,7 @@
 
 - [Introduction](#introduction)
     - [Creating Collections](#creating-collections)
+    - [Extending Collections](#extending-collections)
 - [Available Methods](#available-methods)
 - [Higher Order Messages](#higher-order-messages)
 
@@ -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
 
@@ -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)
@@ -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)
@@ -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)
@@ -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}
 
@@ -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}
 
@@ -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}
 
@@ -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}
 
@@ -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}
 
@@ -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}
 
@@ -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}
 
@@ -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}
 
diff --git a/eloquent-collections.md b/eloquent-collections.md
index 80db3b772c7..070a2cce1c7 100644
--- a/eloquent-collections.md
+++ b/eloquent-collections.md
@@ -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)
@@ -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)
@@ -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)