PHP 类型声明

Begindev 编辑部 March 25, 2026

类型声明（Type Declarations）可以强制规定传递给函数以及函数返回的数据类型。通过指定预期的类型，你将 PHP 从一个在后台默默进行类型转换的语言，变成了一个会主动拒绝无效数据的严谨系统。这能有效地在数据入口处就将 Bug 拦截，而不是等到代码执行了几个小时后才引发崩溃。

1. 标量类型声明 (Scalar Type Declarations)

标量类型声明允许你为函数的参数定义预期的类型。如果指定了类型，在没有开启 strict_types（严格模式）指令的情况下，PHP 会自动尝试将传入的值强制转换为该类型（这被称为“强制类型转换”）。

目前支持的类型包括：int（整型）、float（浮点型）、string（字符串）、bool（布尔型）、array（数组）、callable（可调用对象）、iterable（可迭代对象）、object（对象）以及 mixed（混合类型）。

<?php
declare(strict_types=1);

function calculateArea(int $width, int $height): int {
    return $width * $height;
}

// 正确的用法
echo calculateArea(10, 20); 

// 下面的代码会抛出 TypeError 错误，因为函数预期接收 int，却传入了 string
// echo calculateArea("10", 20);

declare(strict_types=1); 这行指令至关重要。如果没有它，PHP 会执行“强制类型转换”，这意味着 calculateArea("10", 20) 是可以执行成功的，因为 PHP 会强行把字符串 "10" 转换成整数 10。严格模式则会强制要求类型完全匹配，这是编写易于维护的行业标准代码的基石。

2. 返回值类型声明 (Return Type Declarations)

返回值类型声明确保函数始终返回预期的特定数据类型。这为调用该函数的开发者提供了一份清晰的“契约”；他们确切地知道会得到什么结果，而无需去查看函数内部的实现逻辑。

<?php
function getUsername(int $userId): string {
    if ($userId === 1) {
        return "admin";
    }
    return "guest";
}

如果函数内部的逻辑未能返回指定的类型，PHP 会立即抛出一个 TypeError 错误，从而防止返回 null 或意外的数据结构导致后续的程序逻辑崩溃。

3. 可空类型 (Nullable Types)

有时候，函数需要一定的灵活性，既可以返回一个具体的值，也可以什么都不返回（例如，当数据库查询失败时返回空）。你可以通过在类型声明前加上一个问号 (?)，将任何类型设为可空类型（Nullable）。

<?php
function findUserEmail(int $id): ?string {
    $database = [1 => 'user@example.com'];
    return $database[$id] ?? null; // 如果找不到，返回 null
}

// 这是完全合法的调用
$email = findUserEmail(99);

4. Void 返回类型 (The Void Return Type)

当一个函数只执行某种操作（比如写入文件或更新数据库），但不需要返回任何有意义的值时，应该使用 void 返回类型。这明确地传达了一个信息：该函数的结果不应该被用于任何赋值表达式中。

<?php
function logMessage(string $message): void {
    file_put_contents('app.log', $message, FILE_APPEND);
    // 这里不需要显式的 return 语句，
    // 并且该函数绝对不能返回任何值。
}

5. 联合类型 (Union Types)

在复杂的应用程序中，一个函数可能会合理地返回多种不同的类型。联合类型（Union Types）允许你使用管道符 (|) 来指定一个参数或返回值可以是几个预定义类型中的某一个。

<?php
function formatIdentifier(int|string $id): string {
    return "ID_" . $id;
}

echo formatIdentifier(101);    // 输出: ID_101
echo formatIdentifier("A-55"); // 输出: ID_A-55

下面的流程图阐述了类型声明是如何在函数执行过程中扮演“守门员”角色的：

类型校验流程解析：

函数调用 (Function Call)
参数类型检查 (Type Check)

有效类型 (Valid Type) -> 进入函数体执行 (Function Body Execution)
无效类型 (Invalid Type) -> 抛出类型错误 (Throw TypeError)

返回值检查 (Return Value Check)

有效返回类型 (Valid Return Type) -> 成功返回数据 (Return Data)
无效返回类型 (Invalid Return Type) -> 抛出类型错误 (Throw TypeError)