Improve collection return types (#56599)

Author: axlon

src/Illuminate/Collections/Collection.php

@@ -1005,7 +1005,7 @@ public function select($keys)
      * Get and remove the last N items from the collection.
      *
      * @param  int  $count
-     * @return static<int, TValue>|TValue|null
+     * @return ($count is 1 ? TValue|null : static<int, TValue>)
      */
     public function pop($count = 1)
     {
@@ -1127,7 +1127,7 @@ public function put($key, $value)
      *
      * @param  (callable(self<TKey, TValue>): int)|int|null  $number
      * @param  bool  $preserveKeys
-     * @return static<int, TValue>|TValue
+     * @return ($number is null ? TValue : static<int, TValue>)
      *
      * @throws \InvalidArgumentException
      */
@@ -1250,7 +1250,7 @@ public function after($value, $strict = false)
      * Get and remove the first N items from the collection.
      *
      * @param  int<0, max>  $count
-     * @return static<int, TValue>|TValue|null
+     * @return ($count is 1 ? TValue|null : static<int, TValue>)
      *
      * @throws \InvalidArgumentException
      */

types/Support/Collection.php

@@ -691,8 +691,8 @@ function ($collection, $count) {
 assertType('Illuminate\Support\Collection<int, string>', $collection->make(['string'])->concat(['string']));
 assertType('Illuminate\Support\Collection<int, int|string>', $collection->make([1])->concat(['string']));
 
-assertType('Illuminate\Support\Collection<int, int>|int', $collection->make([1])->random(2));
-assertType('Illuminate\Support\Collection<int, string>|string', $collection->make(['string'])->random());
+assertType('Illuminate\Support\Collection<int, int>', $collection::make([1])->random(2));
+assertType('string', $collection::make(['string'])->random());
 
 assertType('1', $collection
     ->reduce(function ($null, $user) {
@@ -997,8 +997,10 @@ function ($collection, $count) {
 assertType('Illuminate\Support\Collection<int, User>', $collection->forget(1));
 assertType('Illuminate\Support\Collection<int, User>', $collection->forget([1, 2]));
 
-assertType('Illuminate\Support\Collection<int, User>|User|null', $collection->pop(1));
-assertType('Illuminate\Support\Collection<int, string>|string|null', $collection::make([
+assertType('User|null', $collection->pop());
+assertType('Illuminate\Support\Collection<int, User>', $collection->pop(2));
+
+assertType('Illuminate\Support\Collection<int, string>', $collection::make([
     'string-key-1' => 'string-value-1',
     'string-key-2' => 'string-value-2',
 ])->pop(2));
@@ -1020,8 +1022,8 @@ function ($collection, $count) {
     'string-key-1' => 'string-value-1',
 ])->put('string-key-2', 'string-value-2'));
 
-assertType('Illuminate\Support\Collection<int, User>|User|null', $collection->shift(1));
-assertType('Illuminate\Support\Collection<int, string>|string|null', $collection::make([
+assertType('User|null', $collection->shift());
+assertType('Illuminate\Support\Collection<int, string>', $collection::make([
     'string-key-1' => 'string-value-1',
     'string-key-2' => 'string-value-2',
 ])->shift(2));