[12.x] Add Arr::push() (#56632)

* Add Arr::push method with dot notation support

Introduces Arr::push to append items to arrays using dot notation. Includes tests for pushing values to nested arrays, handling null keys, and exception cases for invalid types.

* Allow Arr::push to accept multiple values

This better matches array_push's signature

* Update Arr.php

---------

Co-authored-by: Taylor Otwell <[email protected]>

Author: inxilpro

src/Illuminate/Collections/Arr.php

@@ -961,6 +961,23 @@ public static function set(&$array, $key, $value)
         return $array;
     }
 
+    /**
+     * Push an item into an array using "dot" notation.
+     *
+     * @param  \ArrayAccess|array  $array
+     * @param  string|int|null  $key
+     * @param  mixed  $values
+     * @return array
+     */
+    public static function push(ArrayAccess|array &$array, string|int|null $key, mixed ...$values): array
+    {
+        $target = static::array($array, $key, []);
+
+        array_push($target, ...$values);
+
+        return static::set($array, $key, $target);
+    }
+
     /**
      * Shuffle the given array and return the result.
      *

tests/Support/SupportArrTest.php

@@ -70,6 +70,31 @@ public function testAdd()
         $this->assertEquals(['category' => ['type' => 'Table']], Arr::add(['category' => ['type' => 'Table']], 'category.type', 'Chair'));
     }
 
+    public function testPush()
+    {
+        $array = [];
+
+        Arr::push($array, 'office.furniture', 'Desk');
+        $this->assertEquals(['Desk'], $array['office']['furniture']);
+
+        Arr::push($array, 'office.furniture', 'Chair', 'Lamp');
+        $this->assertEquals(['Desk', 'Chair', 'Lamp'], $array['office']['furniture']);
+
+        $array = [];
+
+        Arr::push($array, null, 'Chris', 'Nuno');
+        $this->assertEquals(['Chris', 'Nuno'], $array);
+
+        Arr::push($array, null, 'Taylor');
+        $this->assertEquals(['Chris', 'Nuno', 'Taylor'], $array);
+
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage('Array value for key [foo.bar] must be an array, boolean found.');
+
+        $array = ['foo' => ['bar' => false]];
+        Arr::push($array, 'foo.bar', 'baz');
+    }
+
     public function testCollapse()
     {
         // Normal case: a two-dimensional array with different elements