PHP Fatal error: Declaration Must Be Compatible - Signature Mismatch in CI

PHP enforces the Liskov substitution principle on method signatures. When a child class or interface implementation declares parameters or a return type that are not compatible with the parent or interface, PHP raises a fatal "Declaration must be compatible" error at compile time.

What this error means

CI fails to even load a class with "Declaration of Child::method() must be compatible with Parent::method()". Newer PHP versions made several previously-warning cases fatal, so an upgrade often triggers it.

php

PHP Fatal error:  Declaration of App\Repo::find(\$id): ?App\User must be
compatible with App\Contracts\Finder::find(int \$id): App\User in
/app/src/Repo.php on line 11

Common causes

The override widens or narrows types incompatibly

Adding a stricter parameter type, an incompatible return type, or changing nullability in a way the parent does not allow breaks the contract and is fatal.

A PHP upgrade made the mismatch fatal

Signature compatibility that was a deprecation warning in older PHP became a hard error in newer versions, so an upgrade surfaces a long-standing mismatch in CI.

How to fix it

Match the parent or interface signature exactly

Align parameter types, defaults, and the return type with the contract you are implementing.

php

// interface: find(int \$id): App\User
public function find(int \$id): App\User
{
    return \$this->byId(\$id);
}

Use covariant returns / contravariant params where allowed

PHP permits a more specific (covariant) return type and a more general (contravariant) parameter type. Use those instead of arbitrary changes.

Find every offending override

Read the fatal - it names the child method and the parent/interface it must match.
Grep for other classes implementing the same interface or extending the same base.
Run PHPStan/Psalm to surface remaining signature mismatches before runtime.

How to prevent it

Keep overrides byte-compatible with the contract; let static analysis enforce it.
Review method signatures as part of any PHP version upgrade.
Prefer covariant returns/contravariant params over ad hoc signature changes.