[12.x] Improve types in \Illuminate\Support\Str helper

[shaedrich]

Benefits

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

Highlights

• Closure/callable parameter and return types
• array type narrowing
• number narrowing
• more precise return type when input strings are empty
• non-empty-string assertions
• string narrowing

[shaedrich]

Test failure doesn't seem to be related to changes

[donnysim]

I really wish there was just @phpstan-return for returns like ($needles is array{} ? false : ($haystack is non-empty-string ? bool : false)). It makes IDE support worse and it's such an abomination of a syntax.

[shaedrich]

Fair point 🤔 I used what was already used elsewhere. Let's see what Taylor has to say

[donnysim]

I don't really know if phpstan even has a custom return tag, but others psalm etc. do for the same reason as mentioned. I find it kind of a weird phpstan choice to use custom syntax on an already established tag. Currently have problems with other functions that have this and no explicit return type as it just ends up being mixed in IDE.

[shaedrich]

I don't really know if phpstan even has a custom return tag, but others psalm etc. do for the same reason as mentioned. I find it kind of a weird phpstan choice to use custom syntax on an already established tag. Currently have problems with other functions that have this and no explicit return type as it just ends up being mixed in IDE.

It does:

Prefixed tags

Supported tags (@var, @param, @return, and all generics-related ones) can be prefixed with @phpstan-:

/**
 * @phpstan-param Foo $param
 * @phpstan-return Bar
 */
function foo ($param) { ... }

This is useful in the context of advanced types and generics. IDEs and other PHP tools might not understand the advanced types that PHPStan takes advantage of. So you can leave the ordinary @param in the PHPDoc and add a @phpstan-param with an advanced type syntax.

others psalm etc. do for the same reason as mentioned. I find it kind of a weird phpstan choice to use custom syntax on an already established tag. Currently have problems with other functions that have this and no explicit return type as it just ends up being mixed in IDE.

I didn't know that 😲 That really isn't ideal 😕 Maybe, we should prefix all conditional returns in Laravel 🤔

[donnysim]

I must be bad at searching then 😅 tried to skim through with search and found nothing. As the framework already is embracing phpstan as default it's probably not in interest to yet again get a flood of changes so it is what it is. Saw that PHPStorm tries to support it best it can at the type level but ain't always on point, especially on the nested conditions where it just drops half of the condition types so maybe it will get better and won't matter in the long run. At least from the JetBrains side 😬

[shaedrich]

I must be bad at searching then 😅

Good to know that I'm not the only one who gets a little lost in the PHPStan docs 😅

[wwright216]

I know this has already been merged (and now released) but....

[shaedrich]

Thanks for the suggestions, there's already a PR for this: #58364