Covariance and contravariance in PHP & PHPStan

_resources.md

General resources

• PHP RFC: Parameter Type Widening
• PHP RFC: Return Type Declarations
• https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)
• https://en.wikipedia.org/wiki/Liskov_substitution_principle
• https://en.wikipedia.org/wiki/Type_system
• https://en.wikipedia.org/wiki/Top_type
• https://en.wikipedia.org/wiki/Bottom_type

Other

• PHP types hierarchy - nomnoml diagram
• https://blog.mariusschulz.com/2016/11/18/typescript-2-0-the-never-type
• PHP #externals: [RFC] Parameter No Type Variance
• PHP #externals: Parameter type widening RFC
• https://proandroiddev.com/understanding-generics-and-variance-in-kotlin-714c14564c47

PHPStan playground

• https://phpstan.org/r/5554c17159b690ae226419cec4e1c28b - example of method parameter covariance problem
• https://phpstan.org/r/a77db2e22a4daf7833e6d28c8cc812f8 - example of parametr incompatibility problem (kind of method overload)
• https://phpstan.org/r/59ba52fe399d2ae2ae5d46611bdd3d3e - with native types, contravariant/incompatible @params are correctly ignored but not reported
• return type covariance works well with both @return and @method
  • https://phpstan.org/r/1d8417d93a8b7242f99eaa57203caead - with return types only in PhpDoc
  • https://phpstan.org/r/c12459708c9c390c9f1e06504b3bdbbf - with native return type + PhpDoc
• https://phpstan.org/r/72edb34bc365edc5d88e53e53a713c4f - @method annotation allows to completely change method singature (so according PHPStan correct code will not actually run at all: https://3v4l.org/a45q7), as well as cause problems with parametr covariance and return type contravariance

3V4L

• https://3v4l.org/MEqDv - Method overloading doesn't work really

contravariant-parameter-mixed.php

<?php

// PHP RFC: Parameter Type Widening (Contravariant argument type)
// https://wiki.php.net/rfc/parameter-no-type-variance
// It's not real contravariance. Type widening doesn't allow to use arbitrary supertype, only mixed (by ommiting type).
// Otherwise, parameter types in PHP are invariant.
// This correspond with behaviour of return types, which are kind of covariant
// https://3v4l.org/jU9IC


class A {}
class B extends A {}
class C extends B {}
class X {}

class Foo {
    public function bar(B $b) {}
}

class Woo extends Foo {
    public function bar(/*mixed*/ $b) {}
}

$foo = new Foo();
$woo = new Woo();

// $foo->bar(new A);// A is too generic, Foo::bar() expects more specific type B  
// TypeError: Argument 1 passed to Foo::bar() must be an instance of B, instance of A given
$foo->bar(new B);   // this is ok, B is expected type
$foo->bar(new C);   // this is ok, C is subtype of B
// $foo->bar(new X);// X isn't subtype of B
// TypeError: Argument 1 passed to Foo::bar() must be an instance of B, instance of X given

$woo->bar(new A);   // this is ok, A is subtype of mixed
$woo->bar(new B);   // this is ok, B is subtype of mixed
$woo->bar(new C);   // this is ok, C is subtype of mixed
$woo->bar(new X);   // this is ok, X is subtype of mixed
$woo->bar([]);      // this is ok, array is subtype of mixed 
$woo->bar(123);     // this is ok, int is subtype of mixed

function baz(Foo $f) {
    // Foo:bar() accept only B and its subtypes (ie. B and C) 
    // and these types are safe also for Woo:bar() if Woo is up-casted to Foo
    $f->bar(new C);
}

baz($foo);
baz($woo); // inside of baz function, Woo is up-casted to Foo

covariant-return-mixed.php

<?php

// PHP RFC: Return Type Declarations
// https://wiki.php.net/rfc/return_types
// RFC for return type can be interpreted in the way that PHP has kind of covariation for return types:
// Supertype (top type) mixed can be overidden with more specific type (ie. with any built-in or custom type).
// Otherwise, return types in PHP are invariant.
// This corresponds with behaviour of type widening (contravariance) https://wiki.php.net/rfc/parameter-no-type-variance
// https://3v4l.org/8Rlce

class A {}
class B extends A {}
class C extends B {}
class X {}

class Foo {
    public function bar() /*:mixed*/ { 
        return [];
    }
}

class Woo extends Foo {
    public function bar() :B {
        return new B();
    }
}

$foo = new Foo();
$woo = new Woo();

$foo->bar(); // return type is mixed, returned value can be whatever
$woo->bar(); // return type is B, returned value can be of type B or C only

function baz(Foo $f) {
    $f->bar(); // return type is mixed, 
    // code here can't have any expectation for type of returned value, even if $f contains up-casted Woo 
}

php-types.nomnoml

[true]-:>[bool]
[false]-:>[bool]
[int]-:>[number]
[float]-:>[number]
[number]-:>[scalar]
[bool]-:>[scalar]
[string]-:>[scalar]
[scalar]-:>[mixed]
[object]-:>[mixed]
[array]-:>[mixed]
[iterable]-:>[mixed]
[resource]-:>[mixed]
[callable]-:>[mixed]
[null​]-:>[mixed]
[stdClass]-:>[object]
[DateTime]-:>[object]
[...]-:>[object]
[void]-:>[mixed]

x-argument-contravariance.php

<?php

class A {}

class B extends A {}

class Foo {
    public function bar(B $b) {}
}

class Woo extends Foo {
    public function bar(A $b) {}
}

$w = new Woo();

x-return-covariance.php

<?php

class A {}

class B extends A {}

class Foo {
    public function bar() : A {}
}

class Woo extends Foo {
    public function bar() : B {}
}

$w = new Woo();