[11.x] Add generics for Arr::first() (#50514)

* Add generics for Arr::first()

* Add TKey

src/Illuminate/Collections/Arr.php

@@ -181,10 +181,14 @@ public static function exists($array, $key)
     /**
      * Return the first element in an array passing a given truth test.
      *
-     * @param  iterable  $array
-     * @param  callable|null  $callback
-     * @param  mixed  $default
-     * @return mixed
+     * @template TKey
+     * @template TValue
+     * @template TFirstDefault
+     *
+     * @param  iterable<TKey, TValue>  $array
+     * @param  (callable(TValue, TKey): bool)|null  $callback
+     * @param  TFirstDefault|(\Closure(): TFirstDefault)  $default
+     * @return TValue|TFirstDefault
      */
     public static function first($array, callable $callback = null, $default = null)
     {

types/Support/Arr.php

@@ -0,0 +1,56 @@
+<?php
+
+use Illuminate\Support\Arr;
+
+use function PHPStan\Testing\assertType;
+
+$array = [new User];
+/** @var iterable<int, User> $iterable */
+$iterable = [];
+/** @var Traversable<int, User> $traversable */
+$traversable = [];
+
+assertType('User|null', Arr::first($array));
+assertType('User|null', Arr::first($array, function ($user) {
+    assertType('User', $user);
+
+    return true;
+}));
+assertType('string|User', Arr::first($array, function ($user) {
+    assertType('User', $user);
+
+    return false;
+}, 'string'));
+assertType('string|User', Arr::first($array, null, function () {
+    return 'string';
+}));
+
+assertType('User|null', Arr::first($iterable));
+assertType('User|null', Arr::first($iterable, function ($user) {
+    assertType('User', $user);
+
+    return true;
+}));
+assertType('string|User', Arr::first($iterable, function ($user) {
+    assertType('User', $user);
+
+    return false;
+}, 'string'));
+assertType('string|User', Arr::first($iterable, null, function () {
+    return 'string';
+}));
+
+assertType('User|null', Arr::first($traversable));
+assertType('User|null', Arr::first($traversable, function ($user) {
+    assertType('User', $user);
+
+    return true;
+}));
+assertType('string|User', Arr::first($traversable, function ($user) {
+    assertType('User', $user);
+
+    return false;
+}, 'string'));
+assertType('string|User', Arr::first($traversable, null, function () {
+    return 'string';
+}));