PHP 7.3.14 Released

Covariance and Contravariance

Prior to PHP 7.4.0, class methods support mainly invariant parameter types and invariant return types. This means that if a method within a parent class has a parameter type or return type of T, any child method with corresponding parameter type or return type must also be type T.

As of PHP 7.4.0, covariance and contravariance is supported. While these concepts may sound confusing, in practice they're rather simple, and extremely useful to object-oriented programming.

Covariance

Covariance allows a child's method to return a more specific type than the return type of its parent's method. This is better illustrated with an example.

We'll start with a simple abstract parent class, Animal, which is extended by children classes, Cat, and Dog.

<?php

abstract class Animal
{
    protected 
string $name;

    public function 
__construct(string $name)
    {
        
$this->name $name;
    }

    abstract public function 
speak();
}

class 
Dog extends Animal
{
    public function 
speak()
    {
        echo 
$this->name " barks";
    }
}

class 
Cat extends Animal 
{
    public function 
speak()
    {
        echo 
$this->name " meows";
    }
}

Note that there aren't any methods which return values in this example. We will build upon these classes with a few factories which return a new object of class type Animal, Cat, or Dog. Covariance will come into play in the next example.

<?php

interface AnimalShelter
{
    public function 
adopt(string $name): Animal;
}

class 
CatShelter implements AnimalShelter
{
    public function 
adopt(string $name): Cat // instead of returning class type Animal, it can return class type Cat
    
{
        return new 
Cat($name);
    }
}

class 
DogShelter implements AnimalShelter
{
    public function 
adopt(string $name): Dog // instead of returning class type Animal, it can return class type Dog
    
{
        return new 
Dog($name);
    }
}

$kitty = (new CatShelter)->adopt("Ricky");
$kitty->speak();
echo 
"\n";

$doggy = (new DogShelter)->adopt("Mavrick");
$doggy->speak();

The above example will output:

Ricky meows
Mavrick barks

Contravariance

Contravariance, on the other hand, allows a parameter type to be less specific in a child method, than that of its parent. Continuing with our previous example with the classes Animal, Cat, and Dog, we're adding a class called Food and AnimalFood, and adding a method eat(AnimalFood $food) to our Animal abstract class.

<?php

class Food {}

class 
AnimalFood extends Food {}

abstract class 
Animal
{
    protected 
string $name;

    public function 
__construct(string $name)
    {
        
$this->name $name;
    }

    public function 
eat(AnimalFood $food)
    {
        echo 
$this->name " nom noms " get_class($food);
    }
}

In order to see the behavior of contravariance, we will override the eat method in the Dog class to allow any Food type object. The Cat class remains unchanged.

<?php

class Dog extends Animal
{
    public function 
eat(Food $food) {
        echo 
$this->name " nom noms " get_class($food);
    }
}

Now, we can see how contravariance works.

<?php

$kitty 
= (new CatShelter)->adopt("Ricky");
$catFood = new AnimalFood();
$kitty->eat($catFood);
echo 
"\n";

$doggy = (new DogShelter)->adopt("Mavrick");
$banana = new Food();
$doggy->eat($banana);

The above example will output:

Ricky nom noms AnimalFood
Mavrick nom noms Food

But what happens if $kitty tries to eat the $banana?

$kitty->eat($banana);

The above example will output:

Fatal error: Uncaught TypeError: Argument 1 passed to Animal::eat() must be an instance of AnimalFood, instance of Food given
add a note add a note

User Contributed Notes 1 note

up
1
xedin dot unknown at gmail dot com
13 days ago
I would like to explain why covariance and contravariance are important, and why they apply to return types and parameter types respectively, and not the other way around.

Covariance is probably easiest to understand, and is directly related to the Liskov Substitution Principle. Using the above example, let's say that we receive an `AnimalShelter` object, and then we want to use it by invoking its `adopt()` method. We know that it returns an `Animal` object, and no matter what exactly that object is, i.e. whether it is a `Cat` or a `Dog`, we can treat them the same. Therefore, it is OK to specialize the return type: we know at least the common interface of any thing that can be returned, and we can treat all of those values in the same way.

Contravariance is slightly more complicated. It is related very much to the practicality of increasing the flexibility of a method. Using the above example again, perhaps the "base" method `eat()` accepts a specific type of food; however, a _particular_ animal may want to support a _wider range_ of food types. Maybe it, like in the above example, adds functionality to the original method that allows it to consume _any_ kind of food, not just that meant for animals. The "base" method in `Animal` already implements the functionality allowing it to consume food specialized for animals. The overriding method in the `Dog` class can check if the parameter is of type `AnimalFood`, and simply invoke `parent::eat($food)`. If the parameter is _not_ of the specialized type, it can perform additional or even completely different processing of that parameter - without breaking the original signature, because it _still_ handles the specialized type, but also more. That's why it is also related closely to the Liskov Substitution: consumers may still pass a specialized food type to the `Animal` without knowing exactly whether it is a `Cat` or `Dog`.
To Top