Add extended reasons tips to param out errors

[thg2k]

This adds the very useful tips on complex types also to param-out.

Please carefully review the correctness, I assume that isSuperTypeOf and acceptsWithReason are equivalent.

Also not sure how to set the strictness parameter, as it is a param-out it should not be affected by the strict types declare.

Before:

 ------ ----------------------------------------------------------------------------------------------------------------------------
  Line   case2.php
 ------ ----------------------------------------------------------------------------------------------------------------------------
  8      Parameter &$foo by-ref type of function foo() expects array{a: int, b: int, c: string}, array{a: int, b: int, c: 5} given.
           parameterByRef.type
          You can change the parameter out type with @param-out PHPDoc tag.
 ------ ----------------------------------------------------------------------------------------------------------------------------

After:

 ------ ----------------------------------------------------------------------------------------------------------------------------
  Line   case2.php
 ------ ----------------------------------------------------------------------------------------------------------------------------
  8      Parameter &$foo by-ref type of function foo() expects array{a: int, b: int, c: string}, array{a: int, b: int, c: 5} given.
           parameterByRef.type
          Offset 'c' (string) does not accept type int.
          You can change the parameter out type with @param-out PHPDoc tag.
 ------ ----------------------------------------------------------------------------------------------------------------------------

[ondrejmirtes]

accepts and isSuperTypeOf are not equivalent. The former is about "Does this type accept that type?" and the latter one is "Is this type part of that type?"

Some practical differences:

• Float accepts any int, but float isn't an int
• Without strict_types=1, object of class with __toString (Stringable) is accepted in a string.
• Generics acceptance rules are stricter based on TemplateTypeStrategy

What we could do is implement isSuperTypeOfWithReason. We could use that in all the rules where isSuperTypeOf is used.

Another example besides @param-out where this would be useful is this issue: phpstan/phpstan#10421

[thg2k]

To be very honest I did not fully understand your answer 😄

Is it correct to assume that isSuperTypeOf()->yes() fully implies acceptance? Because in this case I can do it very dirty and attempt to pull the reasons from acceptsWithReason only if isSuperTypeOf check fails.

This way the semantic should be preserved and we still give the user some insights when available, worst case the message stays the same. Please check the updated PR.

[ondrejmirtes]

One piece I forgot to mention: we're using isSuperTypeOf because no native type casting is involved, only PHPDocs. So the type must match otherwise you might end up with inconvenient surprise down the road.

I don't want a hack like that, that's not sustainable. It's worth investing in proper solutions.

[thg2k]

It is a hack indeed, but the isSuperTypeWithReason implementation is too big of an endeavor for me, so feel free to close the PR.

[ondrejmirtes]

I worry that the hack would show non-sensical tips we wouldn't have under control. A proper solution would also have other benefits.

[thg2k]

Note to self:
See also phpstan/phpstan#11460