TypeError — When Type Declarations Throw

TL;DR

Explanation

In PHP 7+, type declarations throw TypeError when violated. With declare(strict_types=1), PHP enforces types strictly at call sites. Without it, PHP coerces where possible (int '5' → 5). TypeError extends Error (not Exception) — catch it separately or use Throwable. Common triggers: passing string to int parameter with strict_types, returning wrong type, violating union types. PHP 8.1 intersection types and DNF types (PHP 8.2) add more ways to throw TypeError.

Common Misconception

Why It Matters

Common Mistakes

• Catching Exception instead of Error or Throwable for TypeError.
• Not using strict_types=1 — coercion hides bugs.
• Returning null from a non-nullable return type — use ?Type or add null to union.

Code Examples

function add(int $a, int $b): int { return $a + $b; }
add('five', 2); // Without strict_types: coercion
// With strict_types=1: TypeError: add(): Argument #1 must be int, string given

declare(strict_types=1);
function add(int $a, int $b): int { return $a + $b; }

try {
    add('five', 2);
} catch (\TypeError $e) {
    throw new \InvalidArgumentException('Numeric values required', 0, $e);
}

References

• ↗ https://www.php.net/manual/en/class.typeerror.php

Tags

Related Terms