What do we mean by return type hinting? Well, it's something that Java has had for quite some time - a way of declaring what data type will be returned from a particular method call. It looks a bit like this:

public Animal getAnimal()
{
    return new Animal();
}

Fairly straight forward. In the method declaration, we can see that the word Animal appears between the visibility modifier (public) and the method name itself, getAnimal(). This tells the compiler, and indeed and programmers working with the class, that the method will return an Animal instance. Client code (and its programmers) then know what interface they will have to work with after the return value has been collected.

This is good stuff!

So what does PHP7's implementation look like? Well, as far as I can deduce from the various articles and RFCs that have been floating about, the PHP version of the above will look something like this.

public function getAnimal(): Animal {
    return new Animal();
}

Syntactically different, but functionally the same. Notice how the return type is declared after the parentheses and before the opening curly brace of the method body. The return type is thus declared by adding a colon (:) and following it by the type declaration.

However, it's worth noting that in the initial release of PHP7, the return type is intended to be invariant. What does this mean for our code? Let's consider an example.

class VehicleFactory
{
    public function create(): Vehicle {

        $vehicle = new Vehicle();

        return $vehicle;
    }
}

So far, all is well. Our create() method declares a return type of Vehicle. However, potential problems arise when we extend this class and override the parent method. Consider the following as how we might normally want to achieve this.

class SportsCarFactory extends VehicleFactory
{
    public function create(): SportsCar {
        $vehicle = new SportsCar();

        return $vehicle;
    }
}

Here I'm relying on the assumption that the SportsCar class extends the Vehicle class in much the same way that the SportsCarFactory extends the VehicleFactory. Normally, when we extend a class like this, it's because we want to provide a more specialised version of the parent class.

However, this won't work any more. The reason being is that the return type of 'SportsCar' declared in the create() method of the child SportsCarFactory differs from the parent method's 'Vehicle' return type declaration.

PHP7 return type hints are of the invariant variety (thus far), which in real terms means that the interpreter will not be able to ascertain that objects of class SportsCar are not also instances of the base Vehicle class. To fix this situation, we would need to amend the create() method declaration so that it matches the parent method. Like so.

class SportsCarFactory extends VehicleFactory
{
    public function create(): Vehicle {
        $vehicle = new SportsCar();

        return $vehicle;
    }
}

The return type hint has been modified back to the Vehicle class, even though the method itself returns a subclass of Vehicle. This now satisfies the invariance requirement of the declaration between parent and child. Will this be something that catches a few developers out? Potentially.

However, the situation is reversed for interfaces. The declaration of an interface is something that we can use quite powerfully to declare a guarantee for what an object that implements it can do. When there are no familial ties between the different types of object that can implement a particular interface, it's immensely useful to declare for the underlying data type that will be returned from a shared method.

Consider the following.

interface Transformable {
    public function setResultSet(ResultSetAbstract $resultSet);

    public function getTransformed(): TransformedResultAbstract;
}

Any object that implements this interface guarantees to produce a return value whose data type is identifiably one of the TransformedResultAbstract child classes. Assuming that the abstract equally declares the interface of what such a beast should be, our client code should be able to work with it confidently.

Return type hinting is a powerful new addition to the language. As long as developers remain thoughtful about maintaining type safety within their applications, this should go a long way towards the prevention of bugs.

It would have been nice to have had covariant type hinting straight off the bat though. Average coders, particularly those that habitually commit inheritance abuse, are likely to get caught out by this and dismiss return type hinting rather than use it. That's my feeling anyway. Do you agree?