[12.x] Improved type hints for when() helper function.

[marcreichel]

This pull request adds more detailed type hints to the when() helper function, allowing PHPStan to better analyze the output. Allowing the usage of when() in higher PHPStan levels (9+) where the output of when() gets provided to another method that requires a specific parameter type.

Examples

// Before
when(random_int(0, 1), 42); // <- mixed

// After
when(random_int(0, 1), 42); // <- 42|null

// Before
when(true, 42); // <- mixed

// After
when(true, 42); // <- 42

// Before
when(random_int(0, 1), 42, 1337); // <- mixed

// After
when(random_int(0, 1), 42, 1337); // <- 42|1337

[github-actions]

Thanks for submitting a PR!

Note that draft PRs are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[shaedrich]

I could have sworn, these types were already part of the helper—I couldn't have been more wrong apparently 🤯

All the better, that someone took on the task 👍🏻

[shaedrich]

LGTM 👍🏻

But I can neither approve nor reject your PR, however, Taylor will eventually.

[gazben]

This change seems to break the typehint for Closures with parameters. Is this intended?

  152    Parameter #2 $value of function when expects (Closure(): void)|void,   
         Closure(garethp\ews\API\Type\NumberedRecurrenceRangeType): void        
         given.                                                                 
         🪪  argument.type                                                      
         💡  Type #1 from the union: Parameter #1 $range of passed callable is  
         required but accepting callable does not have that parameter. It will  
         be called without it.                                                  

The Closure gets the condition as a parameter:

    function when($condition, $value, $default = null)
    {
        $condition = $condition instanceof Closure ? $condition() : $condition;

        if ($condition) {
            return value($value, $condition);
        }

        return value($default, $condition);
    }

    function value($value, ...$args)
    {
        return $value instanceof Closure ? $value(...$args) : $value;
    }