Merge pull request #4803 from driesvints/missing-collection-method

[5.7] Document whenEmpty and whenNotEmpty methods

Author: taylorotwell

collections.md

@@ -157,9 +157,13 @@ For the remainder of this documentation, we'll discuss each method available on
 [unique](#method-unique)
 [uniqueStrict](#method-uniquestrict)
 [unless](#method-unless)
+[unlessEmpty](#method-unlessempty)
+[unlessNotEmpty](#method-unlessnotempty)
 [unwrap](#method-unwrap)
 [values](#method-values)
 [when](#method-when)
+[whenEmpty](#method-whenempty)
+[whenNotEmpty](#method-whennotempty)
 [where](#method-where)
 [whereStrict](#method-wherestrict)
 [whereIn](#method-wherein)
@@ -1926,6 +1930,16 @@ The `unless` method will execute the given callback unless the first argument gi
 
 For the inverse of `unless`, see the [`when`](#method-when) method.
 
+<a name="method-unlessempty"></a>
+#### `unlessEmpty()` {#collection-method}
+
+Alias for the [`whenNotEmpty`](#method-whennotempty) method.
+
+<a name="method-unlessnotempty"></a>
+#### `unlessNotEmpty()` {#collection-method}
+
+Alias for the [`whenEmpty`](#method-whenempty) method.
+
 <a name="method-unwrap"></a>
 #### `unwrap()` {#collection-method}
 
@@ -1985,6 +1999,88 @@ The `when` method will execute the given callback when the first argument given
 
 For the inverse of `when`, see the [`unless`](#method-unless) method.
 
+<a name="method-whenempty"></a>
+#### `whenEmpty()` {#collection-method}
+
+The `whenEmpty` method will execute the given callback when the collection is empty:
+
+    $collection = collect(['michael', 'tom']);
+    
+    $collection->whenEmpty(function ($collection) {
+        return $collection->push('adam');
+    });
+    
+    $collection->all();
+    
+    // ['michael', 'tom']
+    
+    
+    $collection = collect();
+    
+    $collection->whenEmpty(function ($collection) {
+        return $collection->push('adam');
+    });
+    
+    $collection->all();
+    
+    // ['adam']  
+    
+    
+    $collection = collect(['michael', 'tom']);
+    
+    $collection->whenEmpty(function($collection) {
+        return $collection->push('adam');
+    }, function($collection) {
+        return $collection->push('taylor');
+    });
+
+    $collection->all();
+    
+    // ['michael', 'tom', 'taylor']
+
+For the inverse of `whenEmpty`, see the [`whenNotEmpty`](#method-whennotempty) method.
+
+<a name="method-whennotempty"></a>
+#### `whenNotEmpty()` {#collection-method}
+
+The `whenNotEmpty` method will execute the given callback when the collection is not empty:
+
+    $collection = collect(['michael', 'tom']);
+    
+    $collection->whenNotEmpty(function ($collection) {
+        return $collection->push('adam');
+    });
+    
+    $collection->all();
+    
+    // ['michael', 'tom', 'adam']
+    
+    
+    $collection = collect();
+    
+    $collection->whenNotEmpty(function ($collection) {
+        return $collection->push('adam');
+    });
+    
+    $collection->all();
+    
+    // []  
+    
+    
+    $collection = collect();
+    
+    $collection->whenNotEmpty(function($collection) {
+        return $collection->push('adam');
+    }, function($collection) {
+        return $collection->push('taylor');
+    });
+    
+    $collection->all();
+    
+    // ['taylor']
+
+For the inverse of `whenNotEmpty`, see the [`whenEmpty`](#method-whenempty) method.
+
 <a name="method-where"></a>
 #### `where()` {#collection-method}