[12.x] Improve types of Arr helper

[shaedrich]

Benefits

✅ Improved static analysis
✅ Improved type inference
✅ Increased type coverage

Based on

• [12.x] Improve types in \Illuminate\Support\Str helper #58356
• [12.x] Fix and improve \Illuminate\Support\Str types further #58372
• [12.x] Add type tests for \Illuminate\Support\Str #58365
• [13.x] Add parameter and return type hints to Arr::arrayable() #58489 (comment)

Highlights

• true and false literal types instead of bool where possible
• Narrowed whether strings or arrays are null upon return where possible
• Use of generics to infer the return type where possible
• Narrowing of callables where possible
• Definition of array shapes where possible

[calebdw]

@shaedrich, the ::wrap() generics are incorrect and causes unresolvable type warnings in phpstan when the result is used

I would say that all of the time, Arr::wrap() will be called with a union type which the conditional returns are unable to handle (you're going to have to use an actual phpstan extension for more accurate types, maybe open up a Larastan issue); for example, this:

/** @var float[]|float|null $foo */
assertType('array{}|array<float>', Arr::wrap($foo));

fails with the following (as you can see, the float is not wrapped and the array is double wrapped):

 ------ ----------------------------------------------------------------------------- 
  Line   Support/Arr.php                                                              
 ------ ----------------------------------------------------------------------------- 
  184    Expected type array{}|array<float>, actual: array<array<float>|float>|float  
 ------ ----------------------------------------------------------------------------- 

I"ll submit PR to revert this

[shaedrich]

Ah, darn! Thanks for reporting 👍🏻

[calebdw]

I'm working on a fix that's actually pretty close without needing an extension 👍