PHP 7 interfaces, return type hinting and self

PHP 7 interfaces, return type hinting and self

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

PHP 7 Interfaces, Return Type Hinting, and self

When defining contracts in PHP 7, the introduction of return type hinting promised a level of precision that wasn't possible before. However, combining strict typing with inheritance rules immediately revealed a friction point that trips up many developers: the interaction between interface declarations using : self and concrete class implementations.

Consider a scenario where you want to build a fluent interface. You define an interface where every method returns the current instance to enable chaining:

interface iFoo {
    public function bar(string $baz): self;
}

This declaration clearly communicates intent: "Call this method on $this, and receive back the same object type." When implementing iFoo in a class like Foo, you naturally mirror this signature:

class Foo implements iFoo {
    public function bar(string $baz): self {
        echo $baz . PHP_EOL;
        return $this;
    }
}

At first glance, this seems logically consistent. The class Foo is implementing iFoo, so returning a self (which resolves to Foo) should satisfy the contract of returning an iFoo. However, PHP 7 throws a fatal error:

Declaration of Foo::bar(int $baz): Foo must be compatible with iFoo::bar(int $baz): iFoo

The error message is explicit but often confusing. It claims that the return type Foo (derived from self) is incompatible with the interface's expected return type iFoo. This happens because, in PHP 7, a class implementing an interface must match the interface's return types exactly. If the interface says : self, it literally means "return an instance of this specific interface," which is semantically nonsensical for standard classes unless you are dealing with abstract interfaces representing the object itself.

The Covariance Constraint in PHP 7

This behavior stems from a strict interpretation of Liskov Substitution Principle within the context of type hints, but without support for covariance. In languages like Java or C#, return types are covariant. If an interface says : Parent, a child class can legally return : Child because every Child is also a Parent.

PHP 7 did not implement this covariance for return type hints involving interfaces and the keyword self. When you write : self in an interface, PHP treats it as a specific type tied to that interface definition, not as a generic "instance of the implementing class" placeholder. Consequently, your implementation returning Foo fails the check against the interface declaring iFoo.

The Fix: Using static

To resolve this without breaking the fluent chaining pattern, you must change the return type hint in the interface from self to static. The keyword static is covariant in PHP. It tells the compiler: "I am returning an instance of whatever class actually calls this method."

Here is the corrected implementation:

interface iFoo {
    // Using 'static' allows implementations to return their own specific type
    public function bar(string $baz): static; 
}

class Foo implements iFoo {
    public function bar(string $baz): self {
        echo $baz . PHP_EOL;
        return $this;
    }
}

By declaring : static in the interface, you define a contract that accepts any implementation's specific class as the return value. This aligns perfectly with your desire to chain methods on the concrete instance rather than an abstract interface proxy. The error disappears because static encompasses all subclasses of the implementing class.

What About : parent?

You might wonder if using : parent in the interface works. While technically valid for classes, it is rarely appropriate for interfaces. Interfaces are meant to be implemented by various unrelated classes. Using parent implies a rigid hierarchy that often doesn't exist between an interface and its implementers. static remains the robust choice for polymorphic return types in PHP 7.

A Note on PHP Versions

If you are working with PHP 7.4 or later, this specific friction point has been largely addressed regarding covariance and contravariance in more complex scenarios, though the basic rule of using static in interfaces for fluent patterns remains best practice. For projects stuck on earlier versions like 7.0 or 7.1, switching to static is the only viable path forward to achieve type-safe method chaining.

For teams adopting modern PHP practices, ensuring your interface contracts utilize static for return types preserves the ability to write clean, typed fluent APIs without sacrificing type safety. This approach ensures that tools like static analyzers and IDEs can still provide accurate autocomplete and error detection while respecting the polymorphic nature of object-oriented programming in PHP.

Our network