PHP Type Declarations — The $37k Coercion Bug

Every PHP application that lives longer than a weekend starts to rot in the same way: a function that was supposed to receive a price gets passed a product name, a method expecting an integer silently receives a floating-point number and rounds it wrong, and suddenly your invoice totals are off by a cent per line. These bugs are invisible until they hit production, and they're humiliating to explain to a client. Type declarations are PHP's answer to this exact problem — they let you encode your assumptions about data directly into the function signature, so PHP enforces them automatically instead of trusting every caller to get it right.

Before type declarations, PHP's dynamic typing was simultaneously its superpower and its biggest footgun. You could prototype fast, but a large codebase with no type hints was a minefield. A calculateTax(float $amount) declaration does more documentation work than three paragraphs of PHPDoc, and unlike comments, it actually runs. It tells the next developer — and PHP itself — what the contract of this function is, and PHP will throw a TypeError the moment someone violates it.

By the end of this article you'll know how to declare parameter types, return types, nullable types, and union types, and you'll understand the critical difference between coercive mode and strict mode. More importantly, you'll know when each feature earns its keep in real production code, and you'll have a clear mental model for why PHP's type system works the way it does — which is the knowledge that separates developers who use type hints from developers who truly understand them.

Why PHP Type Declarations Are Not Optional

PHP type declarations let you specify the expected type of function parameters, return values, and class properties. The core mechanic is simple: declare a type, and PHP enforces it at runtime. Without them, PHP coerces values silently — '123' becomes 123, 1.0 becomes 1 — which is the root of the $37k bug where a float comparison passed validation because a string '0.01' was coerced to 0, then 0.0, then matched a zero balance check.

By default, PHP uses coercive typing: it converts values to the declared type if possible. Declare strict_types=1 at the file top to switch to strict mode, which throws a TypeError on mismatch. This is a per-file directive, not an application-wide setting — a common source of confusion. Properties and return types are enforced at write/return time; parameter types at call time.

Use type declarations on every function and method in production code. They turn silent data corruption into immediate, catchable errors. In systems handling money, IDs, or user input, strict mode is mandatory. Without them, you're one accidental string-to-int coercion away from a logic bug that passes all tests and corrupts your database.

Parameter & Return Type Declarations — The Core Contract

A type declaration is a promise written into the function signature itself. You place the type before the parameter name (for inputs) and after the closing parenthesis with a colon (for the return value). PHP supports scalar types — int, float, string, bool — along with array, callable, object, class names, and from PHP 8.0 onwards, mixed and never.

The reason this matters isn't just validation. It's communication. When you write function applyDiscount(float $price, int $discountPercent): float, three things happen at once: PHP will enforce those types at runtime, your IDE can autocomplete callers correctly, and static analysis tools like PHPStan can catch type errors before you even run the code. You get documentation, enforcement, and tooling support from a single line.

Return types are arguably more valuable than parameter types, because they constrain your own code. If you declare : string and accidentally return null in one branch, PHP throws a TypeError on that path immediately — not when some caller eventually tries to use the null as a string two stack frames up. That proximity to the bug is priceless in debugging.

<?php

/**
 * Calculates the final price after applying a percentage discount.
 *
 * By declaring float and int types here, PHP guarantees this function
 * can never silently receive a product name or a boolean by accident.
 */
function applyDiscount(float $originalPrice, int $discountPercent): float
{
    if ($discountPercent < 0 || $discountPercent > 100) {
        throw new \InvalidArgumentException(
            "Discount must be between 0 and 100, got {$discountPercent}"
        );
    }

    // PHP coerces "19.99" (string) to 19.99 (float) in non-strict mode.
    // The multiplication result is a float, matching our declared return type.
    $discountMultiplier = 1 - ($discountPercent / 100);
    return round($originalPrice * $discountMultiplier, 2);
}

// Normal usage — works perfectly
$finalPrice = applyDiscount(49.99, 20);
echo "Price after 20% discount: $" . $finalPrice . "\n";

// PHP will coerce the integer 50 to float 50.0 here (coercive mode default)
$salePrice = applyDiscount(50, 10);
echo "Sale price after 10% discount: $" . $salePrice . "\n";

// This next call would throw a TypeError in strict mode — but in coercive mode it might silently convert
// Passing a string that cannot be safely coerced to float:
// applyDiscount('fifty dollars', 10);

strict_types=1 — Coercive Mode vs Strict Mode, and Why It Changes Everything

By default, PHP runs in coercive mode: if you declare int and pass "42", PHP silently converts the string to an integer and carries on. That sounds helpful, but it hides real bugs. If a database query returns "0" (the string) instead of 0 (the integer), coercive mode swallows the difference, and you never know your data pipeline had a problem.

Adding declare(strict_types=1) as the very first line of a PHP file flips the switch: PHP now demands an exact type match. Pass a string where an int is expected and you get a TypeError immediately, no silent conversion. This is the behaviour most statically-typed developers expect PHP to have.

The critical detail that trips up even experienced developers: strict_types is per file. It only affects calls made from that file, not the function definitions themselves. So if strict_types=1 is in your controller file, calls from that controller are strict. But if a third-party library calls your function without strict mode, PHP uses coercive rules for that call. Think of it as the caller setting the rules, not the callee. This is unusual and counterintuitive, so it's worth memorising before your next interview.

<?php
// This declaration MUST be the very first statement in the file.
// It cannot appear after any other code, not even a blank line matters
// (though a comment above <?php is fine in some setups).
declare(strict_types=1);

function calculateShippingCost(int $weightInGrams, float $ratePerKg): float
{
    // Convert grams to kilograms, then multiply by the rate
    $weightInKg = $weightInGrams / 1000;
    return round($weightInKg * $ratePerKg, 2);
}

// VALID: exact types — no coercion needed
$cost = calculateShippingCost(2500, 3.50);
echo "Shipping cost for 2.5kg: $" . $cost . "\n";

// VALID: integer literal 4 is a valid int
$anotherCost = calculateShippingCost(4000, 3.50);
echo "Shipping cost for 4kg: $" . $anotherCost . "\n";

// INVALID in strict mode — will throw TypeError:
// calculateShippingCost("2500", 3.50);
// Fatal error: Uncaught TypeError: calculateShippingCost():
// Argument #1 ($weightInGrams) must be of type int, string given

// ALSO INVALID in strict mode — float 2500.0 is NOT an int:
// calculateShippingCost(2500.0, 3.50);
// Fatal error: Uncaught TypeError: Argument #1 must be of type int, float given

echo "All valid calls completed successfully.\n";

Nullable Types, Union Types & Return-Only Types — Modern PHP's Power Features

Real data isn't always clean. A user's middle name might be null. A function might legitimately return either a string or false. PHP has evolved its type system across versions to handle this reality without abandoning type safety.

Nullable types (PHP 7.1+) use a leading ? to declare that a value can be either the specified type or null. ?string means 'a string or null, nothing else'. This is far more honest than just leaving the type off.

Union types (PHP 8.0+) go further with the pipe syntax: int|float or string|null. This lets you accurately describe functions that genuinely handle multiple types — like a parser that returns a string on success or false on failure.

void is a return-only type that tells PHP — and every future developer — that this function intentionally returns nothing. Not null, not false. Nothing. A void function that has return $something is a TypeError. It's the clearest possible signal that a function works entirely through side effects (writing to a database, sending an email, updating state).

never (PHP 8.1+) is even stronger: it declares the function never returns at all — it always throws an exception or calls exit(). Use it on error handlers and redirectors.

<?php
declare(strict_types=1);

// Simulates a simple in-memory user store for the example
class UserRepository
{
    private array $users = [
        1 => ['id' => 1, 'name' => 'Alice Chen',  'email' => 'alice@example.com', 'nickname' => 'ace'],
        2 => ['id' => 2, 'name' => 'Bob Marley',  'email' => 'bob@example.com',   'nickname' => null],
        3 => ['id' => 3, 'name' => 'Carol White', 'email' => 'carol@example.com', 'nickname' => 'caz'],
    ];

    /**
     * Nullable return type: the user might not exist, so we return
     * the array on success or null on failure — both are valid outcomes.
     *
     * @return array<string,mixed>|null
     */
    public function findById(int $userId): ?array
    {
        // Returns null automatically if the key doesn't exist
        return $this->users[$userId] ?? null;
    }

    /**
     * Nullable parameter: nickname is optional — some users haven't set one.
     * The ?string type is more honest than leaving it as untyped.
     */
    public function updateNickname(int $userId, ?string $nickname): void
    {
        if (!isset($this->users[$userId])) {
            throw new \RuntimeException("User {$userId} not found.");
        }
        // Storing null here is intentional — it clears the nickname
        $this->users[$userId]['nickname'] = $nickname;
    }

    /**
     * Union type return (PHP 8.0+): returns the nickname string if set,
     * or false if the user has no nickname. Both are meaningful results.
     */
    public function getNickname(int $userId): string|false
    {
        $user = $this->findById($userId);
        if ($user === null) {
            throw new \RuntimeException("User {$userId} not found.");
        }
        // Returns false when nickname is null — false means 'not set'
        return $user['nickname'] ?? false;
    }

    /**
     * The void return type says: "I do work but hand nothing back."
     * Trying to use the return value of this method is pointless by design.
     */
    public function logAccess(int $userId): void
    {
        // In production this would write to a log file or database
        echo "[LOG] User {$userId} accessed at " . date('H:i:s') . "\n";
        // A bare 'return;' is allowed in void functions, but returning a value is not
    }
}

$repo = new UserRepository();

// findById returns ?array — we must null-check before using it
$alice = $repo->findById(1);
if ($alice !== null) {
    echo "Found user: " . $alice['name'] . "\n";
}

// User 99 doesn't exist — findById correctly returns null
$ghost = $repo->findById(99);
echo "Unknown user: " . ($ghost === null ? 'not found' : $ghost['name']) . "\n";

// getNickname uses union type string|false
$aliceNick = $repo->getNickname(1);
echo "Alice's nickname: " . ($aliceNick !== false ? $aliceNick : 'none set') . "\n";

$bobNick = $repo->getNickname(2);
echo "Bob's nickname: " . ($bobNick !== false ? $bobNick : 'none set') . "\n";

// updateNickname accepts ?string — passing null clears the nickname
$repo->updateNickname(3, null);
echo "Carol's nickname after clearing: " . ($repo->getNickname(3) !== false ? $repo->getNickname(3) : 'none set') . "\n";

// logAccess returns void — calling it for its side effect only
$repo->logAccess(1);

Mixed and Never Types — The Extremes of PHP's Type System

PHP 8.0 introduced mixed — the type that explicitly says 'I genuinely don't know what this will be'. When you declare a parameter as mixed, PHP accepts literally any value: int, string, object, null, resource, closure. No type check is performed. Use it sparingly — it's the opposite of a type declaration.

The never type (PHP 8.1+) is a return-only type that declares the function never returns normally. It always throws an exception, calls exit(), or hits an infinite loop. This is invaluable for functions like redirectOrDie() or abort() that you want to call without needing to handle a return value.

Together, mixed and never bookend the type system: one says 'I accept everything', the other says 'I give back nothing — ever'.

<?php
declare(strict_types=1);

/**
 * Accepts any type and processes it generically.
 * Use mixed as a last resort — it disables all type safety for this parameter.
 */
function logVar(mixed $data): void
{
    if (is_object($data)) {
        error_log('Object: ' . get_class($data));
    } elseif (is_resource($data)) {
        error_log('Resource type: ' . get_resource_type($data));
    } else {
        error_log('Value: ' . (string) $data);
    }
}

/**
 * A function that never returns — always redirects.
 * Type declared as never, so PHP will enforce that no code after a call to this
 * function is reachable (static analysis can also use this).
 */
function redirectLogout(): never
{
    // Clear session, redirect, then stop
    session_destroy();
    header('Location: /login');
    exit(); // Always terminates
}

logVar('string input');
logVar(42);
logVar(new stdClass());

// The following line would never execute because redirectLogout() exits
// redirectLogout();
echo "This line is unreachable if we call redirectLogout above.";

Type Declarations in Inheritance and Interfaces — Covariance & Contravariance

When you extend a class or implement an interface, PHP enforces signature compatibility. The child method must accept the same parameter types as the parent (or wider types — contravariance). The child must return a narrower type or the same (covariance). This sounds academic, but it matters every time you override a method.

Covariance: A child's return type can be more specific. If the parent returns object, the child can return User. This is safe because every caller expects at least an object — they can handle the more specific type.

Contravariance: A child's parameter types can be less specific. If the parent accepts User, the child can accept object. This is also safe: the child can handle any object, so it can still process a User.

PHP 7.4 introduced covariant return types. PHP 8.0 added contravariant parameter types. Before that, child signatures had to match exactly — pain for many OOP designs.

<?php
declare(strict_types=1);

// Base interface
interface PaymentProcessor
{
    public function charge(float $amount): bool;
}

// A child that returns a more specific type (covariance) is NOT allowed here
// because the parent returns bool, and we can't return a subtype of bool.
// But we can use a more specific parameter type (contravariance) if we widen?
// Actually contravariance means we can accept a wider type as a parameter.
// Let's demonstrate properly:

/**
 * Base class with contravariance example.
 */
class BaseHandler
{
    /**
     * Accepts objects of type \stdClass or wider.
     */
    public function handle(object $data): void
    {
        // base implementation
    }
}

/**
 * Child class uses contravariance: it can accept a wider parameter type (mixed).
 * Note: the parameter type is wider than the parent's (object).
 * This is allowed because any caller that passes object to parent can still pass object to child.
 */
class FlexibleHandler extends BaseHandler
{
    // Contravariance: accepts mixed (wider than object)
    public function handle(mixed $data): void
    {
        // custom implementation
    }
}

// Covariance example with return types
abstract class Factory
{
    abstract public function build(): object;
}

class UserFactory extends Factory
{
    // Covariance: returns a more specific type (User) instead of object
    public function build(): User
    {
        return new User('Alice');
    }
}

class User
{
    public function __construct(public string $name) {}
}

$factory = new UserFactory();
$user = $factory->build();
echo "Built user: " . $user->name . "\n";

PHP 7 Is a Weakly Typed Language — And That's a Trap for the Unwary

Type declarations in PHP don't make PHP strongly typed. They make PHP a weakly typed language where you can optionally slap hints on some function signatures. This isn't a philosophical nitpick — it's a production hazard.

In a truly strongly typed language like Rust or Go, the compiler enforces type rules everywhere, always. Throw an integer at a function expecting a string and the compiler says no. PHP? By default, it shrugs, silently coerces your integer to a string, and moves on. That silent coercion is where bugs breed.

The reason is historical: PHP 7 had to maintain backward compatibility with millions of lines of legacy code. The PHP internals team knew strict types were necessary but couldn't break the ecosystem overnight. So they made type declarations available, but optional. The result is a hybrid: you get type hints, but the engine treats them as suggestions, not contracts — unless you explicitly tell it otherwise.

// io.thecodeforge — php tutorial

// Coercive mode: type hints are suggestions, not rules
declare(strict_types=0); // default, you can omit this line

function processInvoiceId(string $invoiceId): string {
    return strtoupper($invoiceId);
}

$incomingValue = 872344; // integer from some legacy system
$result = processInvoiceId($incomingValue); // coerced silently to "872344"
echo $result; // "872344" — no error, no warning, just a quiet bug

Strict Types Are Imposed on a File-by-File Basis — Yes, Really

Here's the gotcha that sinks teams migrating to strict types: declare(strict_types=1) only applies to the file where you write it. Not to files that call your functions. Not to files you include. One file, and one file only.

This means you can have a strict-typed library file and a coercive-typed consumer calling it with garbage. The coercive caller passes an integer to your strictly typed function — and because the declaration is evaluated per-file, the function's own strict mode is what matters. But only if the function is defined in a strict file. If the caller is loose and the callee is strict, the callee wins. If both are loose, the caller's coercion passes through and the callee never sees the original type.

The architecture forces you to audit every file's header. Miss one include path? Your strict boundary leaks. This isn't academic — I've debugged payment processing pipelines where a single missing declare statement let a float slip through an int parameter, rounding pennies into oblivion.

Pro tip: enforce this with a CI linting rule that checks every PHP file's first line. Painful setup, but cheaper than silent truncation.

// io.thecodeforge — php tutorial

// File: lib/UserRepository.php — strict mode ON
declare(strict_types=1);

function findUser(int $userId): array {
    // expects an integer, strictly
    return ['id' => $userId];
}

// File: controllers/UserController.php — no declare, uses default coercive
// This file calls findUser() with a string
$user = findUser("42"); 
// Because lib/UserRepository.php has strict_types=1, this throws a TypeError at runtime.
// The caller's coercive mode does NOT make the callee accept strings.
// But if lib/UserRepository.php forgot strict_types=1, this would silently coerce.

The Consequences — What Your Production Logs Will Show You

The combination of coercive-by-default and per-file strictness creates three concrete failure modes you will encounter in production.

First: silent data corruption. A function expecting int gets a float due to JSON deserialization. In coercive mode, PHP truncates 12.95 to 12. Your inventory count just lost 0.95 units. No log, no stack trace. Just wrong data.

Second: unexpected TypeError exceptions. You write a library with strict types, a consumer has coercive mode, everything works in dev because inputs are clean. In staging, a third-party API returns "123" instead of 123. Your strictly typed library throws a TypeError that the controller doesn't catch. Now you've got a 500 error in sales reports every Friday.

Third: false confidence in interfaces. You declare an interface method with a string return type, implement it in a strict class, all good. A coworker implements the same interface in a new file without strict_types=1, returns an array instead of a string, and PHP silently coerces it to the string "Array". Your frontend renders "Array" as a username. Users notice.

The fix isn't complex: add declare(strict_types=1) to every file, run static analysis (PHPStan at level max, Psalm at level 2), and enforce both in CI. But knowing the consequences means you stop treating type declarations as a nice-to-have and start treating them as baseline infrastructure.

// io.thecodeforge — php tutorial

// No strict_types=1 — coercive mode is active
function calculateDiscount(float $price): string {
    // Expects float, but receives something that looks like an int
    return sprintf('$%.2f', $price * 0.9);
}

$rawData = json_decode('{"price": 24.99}', true);
// $rawData['price'] is a float 24.99 — works fine

$rawData2 = json_decode('{"price": 25}', true); 
// $rawData2['price'] is an int 25 — silently coerced to float 25.0
// No problem here. But what about this?

$rawData3 = json_decode('{"price": "nineteen"}', true);
$result = calculateDiscount($rawData3['price']);
// PHP coerces "nineteen" to float 0.0 — silent truncation, no error
echo $result; // "$0.00"

Union Types (PHP 8.0) and Intersection Types (PHP 8.1)

Union types allow a parameter, return, or property to accept multiple types, declared using the pipe (|) syntax. For example, int|string accepts either an integer or a string. This is a significant improvement over the old practice of using PHPDoc annotations, as it enforces type checks at runtime. Intersection types, introduced in PHP 8.1, require a value to satisfy multiple type constraints simultaneously, declared with the ampersand (&) syntax, e.g., Countable&Iterator. Intersection types are only applicable to class types (interfaces or classes), not scalar types. Both features enhance type safety and expressiveness. Consider a function that processes a value that could be either an integer or a string: function process(int|string $value): void { ... }. For intersection types, a function might require an object that is both countable and iterable: function process(Countable&Iterator $obj): void { ... }. These features reduce reliance on runtime checks and make code more self-documenting.

<?php

// Union type example
function formatValue(int|string $value): string {
    return match (true) {
        is_int($value) => 'Number: ' . $value,
        is_string($value) => 'String: ' . $value,
    };
}

echo formatValue(42); // Number: 42
echo formatValue('hello'); // String: hello

// Intersection type example (PHP 8.1+)
class MyCollection implements \Countable, \Iterator {
    private array $items = [];
    private int $position = 0;

    public function count(): int { return count($this->items); }
    public function current(): mixed { return $this->items[$this->position]; }
    public function key(): int { return $this->position; }
    public function next(): void { ++$this->position; }
    public function rewind(): void { $this->position = 0; }
    public function valid(): bool { return isset($this->items[$this->position]); }
}

function processCollection(Countable&Iterator $collection): void {
    echo 'Count: ' . count($collection) . PHP_EOL;
    foreach ($collection as $item) {
        echo $item . PHP_EOL;
    }
}

$collection = new MyCollection();
$collection->add('a'); // Assume add() method exists
$collection->add('b');
processCollection($collection);

Mixed Type and True Type (PHP 8.0-8.2)

The mixed type, introduced in PHP 8.0, is the top type that accepts any value. It is equivalent to object|resource|array|string|int|float|bool|null. Using mixed effectively opts out of type checking for that parameter or return, which can be useful in generic contexts or when interfacing with dynamic data. However, overuse defeats the purpose of type declarations. The true type, added in PHP 8.2, is a standalone type that only accepts the boolean value true. This is useful for functions that explicitly return true on success, such as file_put_contents() which returns int|false. With true, you can declare a function that always returns true on success, improving type precision. For example: function isOk(): true { return true; }. Note that false type has existed since PHP 8.0 as a standalone type. These types help document intent and catch bugs where a function might accidentally return a different truthy value.

<?php

// Mixed type example
function debug(mixed $data): void {
    var_dump($data);
}

debug(42);
debug('hello');
debug([1, 2, 3]);

// True type example (PHP 8.2+)
function saveData(string $file, string $data): true {
    $result = file_put_contents($file, $data);
    if ($result === false) {
        throw new \RuntimeException('Failed to write file');
    }
    return true;
}

try {
    saveData('/tmp/test.txt', 'Hello');
    echo 'Saved successfully';
} catch (\Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

Standalone Type null and DNF Types (PHP 8.2)

PHP 8.2 introduced the standalone null type, allowing null to be used as a standalone type declaration. Previously, null could only be part of a union type (e.g., ?int or int|null). Now you can declare a parameter that explicitly expects null: function foo(null $value): void {}. This is rarely needed but can be useful for strict null contracts. More importantly, PHP 8.2 introduced Disjunctive Normal Form (DNF) types, which allow combining union and intersection types with parentheses for clarity. For example, (A&B)|C means either both A and B, or C. This is useful for complex type constraints that were previously impossible to express. DNF types use the syntax (Type1&Type2)|Type3. They are parsed left to right with parentheses to group. For instance, a function that accepts either a Countable&Iterator or an array: function process((Countable&Iterator)|array $data): void {}. This improves type safety for complex scenarios.

<?php

// Standalone null type (PHP 8.2+)
function resetToNull(null $value): void {
    // $value is always null
    var_dump($value);
}

resetToNull(null); // Works
// resetToNull(42); // TypeError

// DNF type example (PHP 8.2+)
interface A {}
interface B {}
class ImplAB implements A, B {}
class ImplA implements A {}

function process((A&B)|string $input): void {
    if ($input instanceof A && $input instanceof B) {
        echo 'Input is A and B';
    } else {
        echo 'Input is string: ' . $input;
    }
}

process(new ImplAB()); // Input is A and B
process('hello'); // Input is string: hello
// process(new ImplA()); // TypeError: must be A&B or string