Reference: Return type of ... should either be compatible with ..., or the #[\ReturnTypeWillChange] attribute should be used

Reference: Return type of ... should either be compatible with ..., or the #[\ReturnTypeWillChange] attribute should be used

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

Stefan Bogdanescu

Founder & Senior Architect

PHP 8.1 and the #[\ReturnTypeWillChange] Attribute

If you are upgrading to PHP 8.1, you will encounter a specific deprecation notice when implementing interfaces that define magic methods. The error message is precise: "Return type of Example::count() should either be compatible with Countable::count(): int, or the #[\ReturnTypeWillChange] attribute should be used." This is not a bug; it is a deliberate shift in how PHP handles interface implementation to improve static analysis and type safety.

The Shift from Duck Typing to Strict Compatibility

In previous PHP versions, the language allowed a degree of flexibility known as duck typing regarding return types. If an interface defined a method returning int or string, implementing that class could return an int or string. While this worked, it created ambiguity for tools like IDEs and static analyzers. They had to rely on runtime reflection to determine if a return type was compatible, which could lead to false positives during code inspection.

PHP 8.1 introduces stricter compatibility rules for interface methods. The core principle is that the declaring class must match the interface definition exactly regarding return types unless explicitly suppressed. For instance, the Countable interface defines the count() method with a strict return type of int. If your implementation attempts to return a float or null without explicit declaration support, PHP flags this as incompatible.

Understanding the Deprecation Notice

When you see the deprecation notice mentioning #[\ReturnTypeWillChange], it is signaling that your current code relies on legacy flexibility that the engine no longer supports by default. The notice offers two distinct paths forward: align your return type with the interface or explicitly mark the method to bypass the check.

Option 1: Align Return Types

The recommended approach is to ensure your implementation matches the interface exactly. If the Countable interface specifies int, your method signature should do the same. This eliminates ambiguity for static analysis tools and ensures that refactoring remains safe across versions.

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

By adding the : int return type hint, you satisfy the engine's requirement for compatibility. This is the preferred method because it leverages PHP's modern type system features without requiring workarounds.

Option 2: Using #[\ReturnTypeWillChange]

If your implementation requires a different return type—for example, if you are using an older version of a library that returns a string representation of the count—you can suppress the warning using the #[\ReturnTypeWillChange] attribute. This attribute tells PHP, "I know this is incompatible, but I intend to handle it correctly at runtime."

class Example implements Countable {
    #[\ReturnTypeWillChange]
    public function count() {
        // Legacy logic that might return a different type
        return (string) 42; 
    }
}

However, using this attribute is generally discouraged unless absolutely necessary. It essentially tells the static analyzer to ignore type mismatches, which can hide potential bugs if your implementation later changes or if the interface definition evolves.

Why This Matters for Laravel Projects

While this change applies to all PHP projects, it is particularly relevant for developers working with frameworks like Laravel. Laravel relies heavily on service contracts and interfaces to define reusable components. When implementing these contracts, adhering to strict type compatibility ensures that your service providers and models integrate seamlessly with the framework's internal mechanisms without triggering unexpected deprecation warnings in production logs.

If you are maintaining legacy codebases that implement interfaces using magic methods or duck-typed return values, transitioning to explicit return types is a necessary step for future-proofing your application. Ignoring these notices now will lead to errors as PHP continues to tighten its type system in upcoming major versions.

Our network