Breaking Down the Error
We've all been there: you deploy a quick update, refresh the page, and get hit with the dreaded "White Screen of Death." When you check your error logs, you find a fatal error complaining about method compatibility. This happens because PHP is a strict enforcer of inheritance rules.
Fatal error: Declaration of ChildClass::methodName($arg) must be compatible with ParentClass::methodName($arg)
The Root Cause
Think of inheritance as a legal contract. If a parent class promises that a method accepts a string, the child class cannot suddenly demand an array. If it did, any code designed to work with the parent would break when it receives the child. This concept is known as the Liskov Substitution Principle.
PHP throws this error during the compilation phase. It happens the moment the engine notices a subclass method signature deviates from its definition in the parent class or interface. This prevents your app from crashing later during execution.
Common Scenarios and Solutions
1. Adding Required Parameters
This is the most frequent culprit. You need extra data in a subclass, so you add a new parameter to the method. However, if that parameter isn't in the parent, the "contract" is broken.
The Problem:
class FileUploader {
public function upload($file) { /* ... */ }
}
class S3Uploader extends FileUploader {
// This fails because $bucket is required but doesn't exist in the parent
public function upload($file, $bucket) { /* ... */ }
}
The Solution: Give the new parameter a default value. By making it optional, the child method remains compatible with the parent's single-argument expectation.
class S3Uploader extends FileUploader {
// Adding a default value (null or an empty string) fixes the mismatch
public function upload($file, $bucket = 'default-vault') { /* ... */ }
}
2. Type Hint Mismatches and Nullability
Since PHP 7.1, nullability (using the ? prefix) has become a common source of these errors. If the parent method allows a null value but the child doesn't, or vice versa, PHP will halt the process.
The Problem:
class UserProfile {
public function update(?string $bio) { /* ... */ }
}
class AdminProfile extends UserProfile {
// Error: Child removed the '?' making it stricter than the parent
public function update(string $bio) { /* ... */ }
}
The Solution: Match the type hints exactly. If the parent uses ?string, the child must also use ?string to maintain the interface.
3. Return Type Inconsistency
Return types became strictly enforced in PHP 7.0. If a parent method specifies it returns an int, the child cannot return a float or a string.
The Problem:
interface CacheProvider {
public function get(string $key): array;
}
class RedisCache implements CacheProvider {
// Error: Missing return type or returning something else
public function get(string $key) { return 'data'; }
}
The Solution: Explicitly define the return type in the child class to match the interface.
class RedisCache implements CacheProvider {
public function get(string $key): array {
return ['data'];
}
}
Modern PHP: Covariance and Contravariance
If you are using PHP 8.0 or later, the rules are slightly more flexible thanks to Variance. You can now use a less specific type for parameters (Contravariance) or a more specific type for return values (Covariance).
- **Parameter Contravariance:** A child can accept `mixed` if the parent accepts `string`.
- **Return Type Covariance:** A child can return a `User` object if the parent returns a generic `BaseModel`.
If these features aren't working, check your php -v. These improvements only fully matured in version 8.0.
How to Verify Your Fix
Don't rely on manual browser refreshes. Use these tools to catch errors in seconds:
- **Terminal Linting:** Run `php -l path/to/file.php`. It checks syntax without running the code.
- **Static Analysis:** Tools like PHPStan or Psalm are life-savers. Running `vendor/bin/phpstan analyse` can find these mismatches across 1,000+ files in under 10 seconds.
- **Signature Copy-Paste:** When in doubt, copy the method line from the parent and paste it directly into the child.
Pro-Tips for Prevention
- **Let the IDE do the work:** Use PhpStorm or VS Code with the Intelephense extension. They highlight mismatches in red text before you even save.
- **The Constructor Exception:** Remember that `__construct` is the odd one out. You can change constructor arguments in a child class freely without triggering this specific fatal error.
- **Composition over Inheritance:** If you find yourself constantly fighting method signatures, it’s a sign. You might need to use composition instead of extending a class that doesn't quite fit your needs.