PHP Type Declarations — The $37k Coercion Bug

<?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);

<?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";

<?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);

<?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.";

<?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";