Doc #79484 [Nab]: Declared full covariance and contravariance support should be refined

Edit report at https://bugs.php.net/bug.php?id=79484&edit=1 ID: 79484 Updated by: nikic@php.net Reported by: vlad dot turchinskiy at yandex dot ru Summary: Declared full covariance and contravariance support should be refined Status: Not a bug Type: Documentation Problem Package: *General Issues Operating System: any PHP Version: 7.4.5 Block user comment: N Private report: N New Comment: What kind of variance is supported for arguments and return values is dictated by the Liskov substitution principle. "Full" support here just means that variance respects all subtyping relationships, as supposed to only some of them, as was the case in earlier PHP versions. Just to make this 100% clear: There will never be support for covariant argument types in PHP, because is simply is not sound. Previous Comments: ------------------------------------------------------------------------ [2020-04-17 09:17:06] vlad dot turchinskiy at yandex dot ru cmb@php.net, > The PHP manual is already clear about that I'm sorry for being annoying, but it isn't. 1) "full covariance and contravariance support" for me means that i can use both in return types and function parameter types. I can't, because of (2) 2) "Function arguments are contra-variant, not co-variant" 3) "contravariance allows a parameter type to be less specific in a child method, than that of its parent." is ok, but what about covariance in parameter type? Nothing. Declared "full support" (1) becomes "partial" without any notice. It is not clear from docs that "Function arguments are contra-variant, not co-variant". This produces "what?!why?!" effect in situations like in test script (https://3v4l.org/vC0WM). ------------------------------------------------------------------------ [2020-04-17 09:00:15] vlad dot turchinskiy at yandex dot ru Fixed category ------------------------------------------------------------------------ [2020-04-17 08:57:56] nikic@php.net Can someone please remove the "PHP Language Specification" category on this bug tracker? php-langspec bug tracker is at https://github.com/php/php-langspec. ------------------------------------------------------------------------ [2020-04-17 08:53:03] cmb@php.net The PHP manual is already clear about that[1]: | Covariance allows a child's method to return a more specific | type than the return type of its parent's method. Whereas, | contravariance allows a parameter type to be less specific in a | child method, than that of its parent. It appears, though, that the language specification is not[2]. [1] <https://www.php.net/manual/en/language.oop5.variance.php> [2] <https://github.com/php/php-langspec/tree/master/spec> ------------------------------------------------------------------------ [2020-04-17 08:21:16] vlad dot turchinskiy at yandex dot ru Description: ------------ On the doc page https://www.php.net/manual/en/language.oop5.variance.php declared that "As of PHP 7.4.0, full covariance and contravariance support was added". As mentioned by derick@php.net at #79482 (https://bugs.php.net/bug.php?id=79482): "Function arguments are contra-variant, not co-variant, meaning that an overloaded/inherited method can chose to accept a broader type. If it would allow for a more specific/narrow type, then an already existing bit of code could no longer call the overloaded with the same method arguments as the original parent class." This should be refined in docs. In the current state, docs goes against POLA (https://en.wikipedia.org/wiki/Principle_of_least_astonishment). Provided test script to demonstrate. Test script: --------------- https://3v4l.org/vC0WM Expected result: ---------------- The fact that "Function arguments are contra-variant, not co-variant" should be mentioned at https://www.php.net/manual/en/language.oop5.variance.php Better, if it had an example. Actual result: -------------- Declared full covariance and contravariance support ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=79484&edit=1