Type Safety in PHP (strict_types & Static Analysis)

Also Known As

TL;DR

Explanation

PHP's type system has evolved substantially: scalar type declarations (PHP 7.0), return types (7.0), nullable types (7.1), typed class properties (7.4), union types (8.0), intersection types (8.1), and DNF types (8.2). Declaring strict_types=1 at the top of a file makes PHP enforce declared types strictly — no silent coercions. But strict_types only applies to function calls within that file. The real force multiplier is static analysis: PHPStan and Psalm infer types through the code graph, catching: passing null where not nullable, incorrect return types, impossible conditions, and missing match arms. Aim for PHPStan level 6+ and full property/return type coverage. Use /** @var Type */ docblocks only where inference is insufficient.

Common Misconception

Why It Matters

Common Mistakes

• Not declaring return types — the method contract is implicit and callers cannot trust the type.
• Using mixed or omitting types on internal methods — type safety degrades from the inside out.
• Not enabling strict_types=1 — PHP silently coerces types without it, hiding mismatches.
• Relying on PHPDoc @return annotations for type safety — they are not enforced at runtime.

Code Examples

// No type declarations — silent type coercion hides bugs:
function calculateDiscount($price, $percent) {
    return $price * ($percent / 100); // '10' * (0.1) = 1.0 — works, but by accident
}
calculateDiscount('ten', '20%'); // No error, returns 0

// With types:
function calculateDiscount(float $price, float $percent): float { /* ... */ }

<?php declare(strict_types=1);

class Money {
    public function __construct(
        public readonly int $amount,
        public readonly string $currency,
    ) {}

    public function add(Money $other): Money {
        if ($this->currency !== $other->currency) {
            throw new CurrencyMismatchException();
        }
        return new Money($this->amount + $other->amount, $this->currency);
    }
}

References

• ↗ https://www.php.net/manual/en/language.types.declarations.php
• ↗ https://phpstan.org/

Tags

Related Terms