42

In PHP 8.1, the following code, which worked in previous versions:

class Example implements Countable {
    public function count() {
        return 42;
    }
}

Raises a deprecation notice:

Deprecated: Return type of Example::count() should either be compatible with Countable::count(): int, or the #[\ReturnTypeWillChange] attribute should be used to temporarily suppress the notice

What does this mean, and how should I fix it?

2 Answers 2

72

Background: Return types and covariance

Since PHP 7.0, it has been possible to specify the return type of a function or method, such as function example(): string to indicate a function that returns a string. This forms a contract that other code can rely on.

For instance, this class promises that the getList method will return some kind of Iterator:

class Base {
    public function getList(): Iterator {
       // ...
    }
}

Calling code can be written knowing that if $foo instanceOf Base is true, then $foo->getList() instanceOf Iterator will also be true.

If you extend the class, you can specify the same return type, or a more specific return type (a rule known as "covariance"), and the calling code's assumption will still be true:

class SubClass extends Base {
    public function getList(): DirectoryIterator {
        // ...
    }
}
$foo = new SubClass;
var_dump($foo instanceOf Base); // true
var_dump($foo->getList() instanceOf Iterator); // true

But if you specify a different return type, or no return type at all, the assumption breaks, so PHP won't allow you to do it:

class NotPossible extends Base {
    public function getList(): bool {
        return false;
    }
}
// Fatal error: Declaration of NotPossible::getList(): bool must be compatible with Base::getList(): Iterator
// If the error didn't happen...
$foo = new NotPossible;
var_dump($foo instanceOf Base); // would be true
var_dump($foo->getList() instanceOf Iterator); // would be false!

Backwards compatibility and deprecation

If you add a return type to an existing class or interface, every class extending or implementing must also be changed, or it will give the same error as in the NotPossible example above.

With the addition of Union Types in PHP 8.0, the return types of most internal functions and methods can be specified; but specifying it for any class or interface method not marked final would have immediately broken a lot of code.

So, instead, the concept of a "tentative" return type was added: the correct return types were documented, but what would normally be an error is instead the deprecation notice shown in the question.

The #[\ReturnTypeWillChange] attribute

The extra problem is that a lot of code needs to be able to run on multiple versions of PHP, and some of the added return types aren't valid in versions before 8.0. So, to indicate a planned change to the returned type in your code, you can add the special attribute #[\ReturnTypeWillChange]. This looks like a comment to older versions of PHP, but tells PHP 8.1 not to raise the deprecation notice. Then, once you don't need to support older versions of PHP, you can fix the return type.

What should you do now?

Firstly, read the message carefully to find out which method you need to change, and what the correct return type is. In the example above:

Return type of Example::count() ...

This says the count method on the Example class needs changing ...

... should either be compatible with Countable::count(): int ...

... and the expected return type is int, as defined on the Countable interface

Next, decide what you can do:

  • Is the code that needs to change in a library or extension written be someone else? Check if there is a new version available. Since this is only a deprecation, it's OK to ignore it and give the author time to fix it.
  • Does your class already return the correct type? In our example, yes, 42 is valid for a return type of int.
  • Can you safely change the return type of the method? If you're working on your own application, the answer is probably "yes", as long as you update classes that extend this one. If you're working on library code where users might have extended this class, you will need to consider the impact on them.

If you decide it's safe, you can simply add the return type as shown in the notice:

class Example implements Countable {
    public function count(): int {
        return 42;
    }
}

If you need to support older versions of PHP, or users who won't have updated their code yet, you can temporarily suppress the notice:

class Example implements Countable {
    #[\ReturnTypeWillChange]
    public function count() {
        return 42;
    }
}

It's important to note that the internal return types will probably be enforced in PHP 9.0, so make sure you have a solid plan to change methods you mark with this attribute.

10
  • I wonder why we don't see this deprication with Stringable? 3v4l.org/Plutn#v8.1.2
    – Rain
    Commented Feb 16, 2022 at 12:55
  • 1
    @Rain Stringable is a weird special case, which defies the normal rules of the language for reasons I don't really understand. You do however get an error if you provide the wrong return type for __toString, regardless of explicitly mentioning the interface: 3v4l.org/fcNql
    – IMSoP
    Commented Feb 16, 2022 at 13:11
  • 2
    @giftnuss #[\ReturnTypeWillChange] will "work" fine under PHP 5, because it is seen as a comment. The chances of supporting both PHP 5 and PHP 9 in the same application are pretty slim, though, so if you're really stuck supporting PHP 5 (which had its final official release over 3 years ago), you might be best off just ignoring all deprecations until you can modernise.
    – IMSoP
    Commented Feb 21, 2022 at 18:15
  • 1
    @IMSoP I want to support older windows. The newer PHPs have dropped support for this platform, which is kind of code obsolescence. PHP5 is mostly a nice programming language and being backwards compatible is a feature, not a bug.
    – giftnuss
    Commented Feb 23, 2022 at 6:21
  • 2
    @giftnuss PHP5 is EOL and does not receive any security coverage or patches. Any security vulnerability that exists will likely never receive a fix, even if it's discovered. It's fine to have backwards compatible code, but it's not safe to use PHP5 anymore because it's unsupported.
    – mbomb007
    Commented Jun 10, 2022 at 13:54
-2

My issue is solve by adding #[\ReturnTypeWillChange] before the functions.

5
  • 5
    This doesn't really say anything that's not in the error message itself, and as my answer explains, this is probably not the right solution if you're just upgrading your own application and don't need to support multiple versions of PHP. There's also no reason to take a screenshot of text; just paste the text into the answer directly.
    – IMSoP
    Commented Oct 6, 2022 at 11:10
  • 1
    As a workaround, it works, and it is one of the options recommended by the very same error reported in the log. Commented Feb 28, 2023 at 18:31
  • 2
    @RodrigoPolo It is also one of the options discussed in my answer, posted 10 months before this one, using actual text rather than a screenshot. If the answer actually gave more details about a situation where this was the right approach, it might have value; but it does not.
    – IMSoP
    Commented May 6, 2023 at 20:59
  • When I was debugging my code, I was getting this error in this function, and by writing #[ReturnTypeWillChange], I was able to solve it. That's why I just copied and pasted the screenshot because I was seeing this in other functions as well. Commented May 8, 2023 at 7:23
  • 1
    @AashirAzeem OK, but did you understand why adding that line fixed it, and when this would be the appropriate thing to do? What do you hope a reader of your answer will learn that isn't already in the error message itself, and in the existing answer on this page?
    – IMSoP
    Commented May 16, 2023 at 6:44

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.