PHP fatal error: a method declaration must be compatible with its parent
Fatal 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.
Fix it fast
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"));'2Match what you see, then jump to its fix
- 1
Declaration of Extend::foo() must be compatible with Base::foo(int $a = 5)The child changes the number or optionality of parametersFix - 2
The 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
The 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
- 1
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.php2Fix
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
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/*.php2Fix
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
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/package3Verify
Run the app or the tests. The class loads without the fatal error.
php -l src/Child.php && composer validateConfirmed by php.net
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
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack 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 fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fixBack end
AWS SDK for PHP rejects requests: the signature is from the future
Signature not yet current: {date} is still later than {date}
AWS compares the timestamp in your signed request with its own clock.
2 causes, each with a fix