[12.x] Improve typehints for Http classes

[cosmastech]

I didn't quite get everything here, but I made some updates to improve typehints and static analysis.

[timacdonald]

I don't think we should be introducing phpstan specific types or more generally try to optimize for PHPStan or other singular tool. Optimizing for a narrow scope like that will lead to detrimental impacts on the wider developer experience outside of phpstan analyze.

We should be testing more exotic changes like these changes against PHPStorm, VSCode, Intelephense language server, Phpactor language server, Psalm, etc.

[cosmastech]

I don't think we should be introducing phpstan specific types or more generally try to optimize for PHPStan or other singular tool. Optimizing for a narrow scope like that will lead to detrimental impacts on the wider developer experience outside of phpstan analyze.

We should be testing more exotic changes like these changes against PHPStorm, VSCode, Intelephense language server, Phpactor language server, Psalm, etc.

I chose this because it feels a lot cleaner than just duplicating the array shapes/closure params again and again. Also, the relationship of the parent method to child methods means that it's very easy for someone to update one but not the others, which is eliminated by this local type alias.

But I can see your point. I believe there's already been at least one PR merged that has them (I was the offender on that one as well). Will be interesting to see if there are any issues that arise from that.

I can assure you that they work fine in the latest version of PHPStorm. As for the others, which I do not use:

• Intelephense appears to have some support for phpstan-type. I grepped through intelephense.js and it's contained there, but it's minified code so 🤷
• It does look like Psalm is designed to handle phpstan-type
• as well as phpactor.

Is there any kind of consensus on what PHPDoc declarations are broadly compatible? If there were somewhere that defined the standards for Laravel typehints, then I think contributors could improve the codebase with confidence. I hope that there's a path forward, because static analysis is a boon to our codebase. Having vendor code without precise types slows down development and introduces bugs that could've been caught.

[taylorotwell]

I do feel like I'm getting DocBlock maintenance fatigue, and I think every DocBlock PR should now be required to provide before and after screenshots of the improvements or changes to PHPStorm / VSCode experience and description of the concrete improvements to static analysis before / after.

[shaedrich]

Would be great if someone could create a GitHub action to do this automatically (maybe there's already one for our use case 🤔)

[cosmastech]

So, as I was working on trying to get some screenshots, two things became apparent.

1. Having callable as a parameter type negates any benefit of having a more precise Closure specified. That is, static analysis won't fail if I pass a closure that doesn't return a bool to Http::assertSent() because I've still passed a callable.
2. Most people will access the Http Factory methods via the facade. But the facade documenter doesn't keep the fidelity of the types.

So, for instance:

$recordedFromFacade = Http::recorded();
\phpstan\dumpType($recordedFromFacade); //  Dumped type: Illuminate\Support\Collection

$recordedFromInstance = app(\Illuminate\Http\Client\Factory::class)->recorded();
\phpstan\dumpType($recordedFromInstance); // Dumped type: Illuminate\Support\Collection<int, array{Illuminate\Http\Client\Request, Illuminate\Http\Client\Response|null}>

While I do think it's helpful to have types specified inside of class itself, I think the real benefit would be if the facade documenter didn't strip that additional data out. I have perused that package, but admit that it would take me a while before I could get anywhere with it.

My question to @taylorotwell would be: do you think there's still benefit to adding stronger type-hinting to the classes, knowing that the benefit is lost to Facades? (Until we update the facade documenter, but... uh.... nose goes 👉👃 on that one today) 😆