Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP fatal error: a method declaration must be compatible with its parent

ErrorFatal error: Declaration of Child::method() must be compatible with Parent::method()

Short answer

PHP requires an overriding method to be usable wherever the parent method is. The error message prints both signatures: compare them. Fix the child so it keeps every required parameter, adds only optional ones, does not narrow parameter types and does not widen return types. From PHP 8.0 a mismatch is fatal, where PHP 7 only warned.

  • Applies to PHP 8.3, PHP 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the message: the first signature is your child method, the second is the parent it must match. Print the parent's declaration from the code if the file is in vendor.

    php -r 'echo (new ReflectionMethod("ParentClass", "methodName"));'
  2. 2Match what you see, then jump to its fix

    1. 1Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5)The child changes the number or optionality of parametersFix
    2. 2The parameter names match, but types differ, for example int against string, or a class against its parent classParameter or return types are narrower or wider than allowedFix
    3. 3The same code ran on PHP 7 with only a warning, and the error appeared after a PHP upgradeOlder code was moved to PHP 8, where the mismatch is fatalFix

What does the error look like?

  • Fatal error: Declaration of Child::method() must be compatible with Parent::method()
  • must be compatible with

Cause 1 of 3

The child changes the number or optionality of parameters

1Check

PHP accepts a child that makes a mandatory parameter optional or adds new optional parameters. It rejects one that removes a parameter or makes an optional one mandatory. Put the two signatures from the message side by side.

php -l src/Child.php && grep -n 'function methodName' src/Parent.php src/Child.php

2Fix

Give the child the same parameters as the parent. If it needs more, add them after the parent's ones with a default value.

class Base {
    public function foo(int $a = 5) {}
}

class Extend extends Base {
    public function foo(int $a = 5, string $extra = '') {
        parent::foo($a);
    }
}

3Verify

Load the class. The fatal error is gone and the script continues.

php -l src/Child.php && php -r 'require "vendor/autoload.php"; new Extend();'

Confirmed by php.net

Did this fix it?

Cause 2 of 3

Parameter or return types are narrower or wider than allowed

1Check

The manual's variance rules: a parameter type may become less specific in the child (contravariance), and a return type may become more specific (covariance). The opposite directions are fatal.

grep -n 'function adopt' src/*.php

2Fix

Change the child's types to follow those directions. Widen parameter types, narrow return types, or change the parent and every implementation together.

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

class CatShelter implements AnimalShelter {
    public function adopt(string $name): Cat { // narrower return type is allowed
        return new Cat($name);
    }
}

3Verify

Load the classes again. The declaration check passes.

php -l src/CatShelter.php && php -r 'require "vendor/autoload.php"; new CatShelter();'

Confirmed by php.net

Did this fix it?

Cause 3 of 3

Older code was moved to PHP 8, where the mismatch is fatal

1Check

The manual says a signature mismatch gave an E_WARNING before PHP 8.0.0 and is a fatal error now. Check which PHP version runs and which file holds the child class.

php -v
php -r 'echo (new ReflectionClass("Child"))->getFileName();'

2Fix

Edit your own classes to match the parent. For a class in vendor, move to a release of that package made for your PHP version instead of patching vendor files. Constructors and private methods are exempt from these rules, so a constructor mismatch is never the cause.

composer outdated vendor/package
composer update vendor/package

3Verify

Run the app or the tests. The class loads without the fatal error.

php -l src/Child.php && composer validate

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Change a parent method and all of its children in one commit.
  • Declare parameter and return types on interfaces, so a mismatch shows when the class loads, not in production.
  • Run the test suite on the PHP version you deploy before upgrading the server.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.