Return Type Declarations (PHP 7.0)
debt(d5/e3/b3/t5)
Closest to 'specialist tool catches it' (d5). The detection_hints list phpstan, psalm, and rector as tools — all specialist static analysis tools, not default linters. Missing return types or wrong return types are caught by running PHPStan at level 6+, not by standard PHP syntax errors or a basic linter.
Closest to 'simple parameterised fix' (e3). The quick_fix states 'Add return type to every function. Use ?Type for nullable, void for no return, never for always-throws. Run PHPStan level 6+ to find missing return types.' This is a repetitive but straightforward annotation pattern — not a one-line patch (there are many functions) but also not a multi-file architectural change. Rector can automate much of this, keeping it at e3.
Closest to 'localised tax' (b3). The choice applies to web, cli, and queue-worker contexts (broad), but the burden is a per-function annotation tax rather than a cross-cutting architectural constraint. Once return types are added, they live locally on each function and don't reshape the rest of the codebase. Future maintainers pay a small ongoing cost to keep return types correct, but it doesn't create strong gravitational pull.
Closest to 'notable trap' (t5). The misconception field explicitly states: 'Return types are only checked by static analysis — PHP enforces return types at runtime too, throwing TypeError for violations.' This is a well-documented gotcha — developers coming from optional-typing mindsets assume return types are purely advisory, but PHP 7.0+ enforces them at runtime. This is a notable, documented surprise but not a catastrophic contradiction with a similar concept elsewhere.
TL;DR
Explanation
Return types declared with colon: function getName(): string. PHP 7.1 added: ?Type (nullable), void (must not return a value or return;). PHP 8.0 added: static (returns same class). PHP 8.1 added: never (function always throws or exits). PHP 8.0 also: mixed (any type — avoid), union types (int|string). Return types are enforced at runtime — returning wrong type throws TypeError. Key discipline: always declare return types. void functions may not return a value. never is for functions that always throw: function fail(): never { throw new Exception(); }.
Common Misconception
Why It Matters
Common Mistakes
- Not adding return types — PHPStan can't verify without them.
- Returning null from a non-nullable return type — add ?Type or handle it.
- Not using void for functions that don't return — allows accidental return values.
Code Examples
function getUser(int $id) { // No return type
return $this->db->find($id) ?? false; // Inconsistent return
}function getUser(int $id): ?User {
return $this->db->find($id); // Null if not found
}
function deleteUser(int $id): void {
$this->db->delete($id);
// Cannot return a value
}
function abort(string $msg): never {
throw new HttpException($msg);
}