PHP Type Declarations Explained — Parameters, Returns & Strict Mode

<?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 — passing a string that
// cannot be safely coerced to float (uncomment to see the error):
// 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);