[8.x] Add a mergeToTop() method

src/Illuminate/Collections/Collection.php

@@ -700,11 +700,25 @@ public function mapWithKeys(callable $callback)
      * Merge the collection with the given items.
      *
      * @param  mixed  $items
+     * @param  bool   $appendToTop
      * @return static
      */
-    public function merge($items)
+    public function merge($items, $appendToTop = false)
     {
-        return new static(array_merge($this->items, $this->getArrayableItems($items)));
+        return $appendToTop
+            ? new static(array_merge($this->getArrayableItems($items), $this->items))
+            : new static(array_merge($this->items, $this->getArrayableItems($items)));
+    }
+
+    /**
+     * Merge the collection, but append the given items at the top.
+     *
+     * @param  mixed  $items
+     * @return static
+     */
+    public function mergeToTop($items)
+    {
+        return $this->merge($items, $appendToTop = true);
     }
 
     /**

src/Illuminate/Collections/LazyCollection.php

@@ -698,6 +698,17 @@ public function merge($items)
         return $this->passthru('merge', func_get_args());
     }
 
+    /**
+     * Merge the collection, but append the given items at the top.
+     *
+     * @param  mixed $items
+     * @return static
+     */
+    public function mergeToTop($items)
+    {
+        return $this->passthru('mergeToTop', func_get_args());
+    }
+
     /**
      * Recursively merge the collection with the given items.
      *

src/Illuminate/Database/Eloquent/Collection.php

@@ -315,7 +315,7 @@ public function modelKeys()
      * @param  \ArrayAccess|array  $items
      * @return static
      */
-    public function merge($items)
+    public function merge($items, $appendToTop = false)
     {
         $dictionary = $this->getDictionary();
 

tests/Support/SupportCollectionTest.php

@@ -1031,6 +1031,15 @@ public function testMergeArray($collection)
         $this->assertEquals(['name' => 'Hello', 'id' => 1], $c->merge(['id' => 1])->all());
     }
 
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testMergeArrayWithoutKeys($collection)
+    {
+        $collection = new $collection(['Apple', 'Banana']);
+        $this->assertEquals(['Apple', 'Banana', 'Pineapple'], $collection->merge(['Pineapple'])->all());
+    }
+
     /**
      * @dataProvider collectionClassProvider
      */
@@ -1040,6 +1049,51 @@ public function testMergeCollection($collection)
         $this->assertEquals(['name' => 'World', 'id' => 1], $c->merge(new $collection(['name' => 'World', 'id' => 1]))->all());
     }
 
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testMergeCollectionWithoutKeys($collection)
+    {
+        $collection = new $collection(['Banana', 'Apple']);
+        $this->assertEquals(['Banana', 'Apple', 'Pineapple'], $collection->merge(new $collection(['Pineapple']))->all());
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testMergeArrayAppendToTop($collection)
+    {
+        $collection = new $collection(['Apple', 'Banana']);
+        $this->assertEquals(['Pineapple', 'Apple', 'Banana'], $collection->merge(['Pineapple'], $appendToTop = true)->all());
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testMergeCollectionAppendToTop($collection)
+    {
+        $collection = new $collection(['Banana', 'Apple']);
+        $this->assertEquals(['Pineapple', 'Banana', 'Apple'], $collection->merge(new $collection(['Pineapple']), $appendToTop = true)->all());
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testMergeArrayAppendToTopAsMethod($collection)
+    {
+        $collection = new $collection(['Apple', 'Banana']);
+        $this->assertEquals(['Pineapple', 'Apple', 'Banana'], $collection->mergeToTop(['Pineapple'])->all());
+    }
+
+    /**
+     * @dataProvider collectionClassProvider
+     */
+    public function testMergeCollectionAppendToTopAsMethod($collection)
+    {
+        $collection = new $collection(['Banana', 'Apple']);
+        $this->assertEquals(['Pineapple', 'Banana', 'Apple'], $collection->mergeToTop(new $collection(['Pineapple']))->all());
+    }
+
     /**
      * @dataProvider collectionClassProvider
      */