Type Declarations Overview

Also Known As

TL;DR

Explanation

PHP's type system has grown substantially: PHP 7.0 added scalar type hints (int, float, string, bool) and return types; 7.1 added nullable (?Type) and void; 7.4 added typed properties; 8.0 added union types (A|B), mixed, static return type, and the never placeholder; 8.1 added intersection types (A&B), never return type, and readonly properties; 8.2 added standalone null, false, true types. Combine with declare(strict_types=1) for strict runtime enforcement. Static analysers (PHPStan, Psalm) use these to verify type correctness without execution.

Common Misconception

Why It Matters

Common Mistakes

• Not enabling strict_types=1 — without it PHP coerces types silently, defeating much of the safety benefit.
• Using mixed or no type at all "just in case" — be as specific as possible, loosen only when truly needed.
• Declaring nullable types (?string) out of habit when null is never a valid input.
• Forgetting return type declarations — parameter types alone leave the output unguarded.

Avoid When

• Avoid mixed as a type declaration — it disables type checking entirely and signals unclear design.
• Do not use type declarations as a substitute for input validation on data coming from outside PHP.

When To Use

• Declare parameter and return types on all public methods — they serve as enforced documentation.
• Use declare(strict_types=1) at the top of every PHP file to prevent silent type coercion.

Code Examples

// No type declarations — bugs hide until runtime:
function applyDiscount($price, $percent) {
    return $price - ($price * $percent / 100);
}
applyDiscount('ten dollars', '20%'); // No error — returns 0

// With type declarations:
function applyDiscount(float $price, float $percent): float {
    return $price - ($price * $percent / 100);
}
applyDiscount('ten dollars', '20%'); // TypeError immediately

<?php declare(strict_types=1);

class UserService {
    // Typed property (PHP 7.4)
    private array $cache = [];

    // Parameter + return types
    public function findById(int $id): ?User { return null; }

    // Union type (PHP 8.0)
    public function findByIdOrEmail(int|string $identifier): ?User { return null; }

    // Intersection type (PHP 8.1) — must be Countable AND Iterator
    public function processAll(\Countable&\Iterator $items): void {}

    // never return type (PHP 8.1)
    public function fail(string $msg): never {
        throw new \RuntimeException($msg);
    }

    // Enum param (PHP 8.1)
    public function filterByStatus(OrderStatus $status): array { return []; }
}

References

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

Tags

Related Terms