PHP: 类型声明

类型声明

类型声明可以用于函数的参数、返回值， PHP 7.4.0 起还可以用于类的属性， PHP 8.3.0 起还可以用于类的常量。如果预期类型在调用时不匹配，则会抛出一个 TypeError 异常。

PHP 支持各种单一类型，除了 resource 之外，都可以用于用户级别类型声明。这个页面包含了不同类型间的可用性变更日志以及在类型声明中用法的文档。

注意:
当类实现了接口方法或者重新实现了父级类中定义的方法时，必须与上述定义兼容。如果方法遵循方差规则，则兼容该方法。

更新日志

版本	说明
8.3.0	新增了对类、接口、trait 和枚举常量类型的支持。
8.2.0	新增对 DNF 类型的支持。
8.2.0	新增对 literal 类型 true 的支持。
8.2.0	现在可以单独使用 null 和 false。
8.1.0	新增对交集类型的支持。
8.1.0	弃用 void 函数通过引用返回。
8.1.0	新增对返回类型 never 的支持。
8.0.0	新增对 mixed 类型的支持。
8.0.0	新增对返回类型 static 的支持。
8.0.0	新增对联合类型的支持。
7.4.0	新增对类属性类型化的支持。
7.2.0	新增对 object 类型的支持。
7.1.0	新增对 iterable 类型的支持。
7.1.0	新增对 void 类型的支持。
7.1.0	新增对可为 null 类型的支持。

原子类型使用说明

原子类型具有直接明了的行为，但存在一些细微注意事项，本节对此进行了描述。

标量类型

警告

标量类型（bool、int、float、string）不支持别名。别名反而会视为类或接口名。例如，使用 boolean 作为类型声明，将要求值是 instanceof 类或接口 boolean，而不是类型 bool。

<?php
    function test(boolean $param) {}
    test(true);
?>

以上示例在 PHP 8 中的输出：

Warning: "boolean" will be interpreted as a class name. Did you mean "bool"? Write "\boolean" to suppress this warning in /in/9YrUX on line 2

Fatal error: Uncaught TypeError: test(): Argument #1 ($param) must be of type boolean, bool given, called in - on line 3 and defined in -:2
Stack trace:
#0 -(3): test(true)
#1 {main}
  thrown in - on line 2

void

注意:
从 PHP 8.1.0 起弃用 void 函数通过引用返回，因为这样的函数自相矛盾。在此之前调用时总是会发出如下 E_NOTICE：Only variable references should be returned by reference。

<?php function &test(): void {} ?>

Callable 类型

此类型不能用于类属性的类型声明。

注意: 无法指定函数的签名。

通过引用传递的参数类型

如果通过引用传递的参数有类型声明，则变量的类型仅在调用函数时检查，返回时不会检查。这意味着函数可以改变引用变量的类型。

示例 #1 通过引用传递的参数类型

<?php
function array_baz(array &$param)
{
    $param = 1;
}
$var = [];
array_baz($var);
var_dump($var);
array_baz($var);
?>

以上示例的输出类似于：

int(1)

Fatal error: Uncaught TypeError: array_baz(): Argument #1 ($param) must be of type array, int given, called in - on line 9 and defined in -:2
Stack trace:
#0 -(9): array_baz(1)
#1 {main}
  thrown in - on line 2

复合类型使用说明

复合类型声明有几个限制，并且在编译时执行冗余检查以避免简单的错误。

警告

在 PHP 8.2 之前，也就是没引入 DNF 之前，交集类型和联合类型不能组合使用。

联合类型

警告

在一个联合类型中不能同时用两个 Value 类型 false 和 true。而是使用 bool 替代。

警告

在 PHP 8.2.0 之前，由于 false 和 null 不能作为独立的类型使用，因此不允许仅由这些类型组成联合类型。这还包括以下类型：false、false|null, 和 ?false。

可为 null 类型语法糖

单个基本类型声明可以通过在类型前添加问号（?）来标记可为 null。因此 ?T 和 T|null 是相同的。

注意: 该语法自 PHP 7.1.0 起支持，且早于完整的（generalized）联合类型支持。

注意:
也可以通过设置参数的参数的默认值为 null 来实现允许为 null。但并不建议这么做，因为如果在子类中更改了默认值，会引发类型兼容冲突，需要将 null 类型添加到类型声明中。
示例 #2 使参数可以为 null 的旧方法

<?php class C {} function f(C $c = null) { var_dump($c); } f(new C); f(null); ?>

以上示例会输出：
object(C)#1 (0) {
}
NULL

重复冗余的类型

为了能捕获复合类型声明中的简单错误，不需要类加载检测到的冗余类型将导致编译时错误。包含：

解析出来的类型只能出现一次。例如这样的类型 int|string|INT 或 Countable&Traversable&COUNTABLE 会导致错误。
使用 mixed 会导致错误。
对于联合类型：
- 使用了 bool 时就不能再附带使用 false 或者 true。
- 使用了 object 时就不能再附带使用 class 类型。
- 使用了 iterable 时，不能再附带使用 array 和 Traversable。
对于交集类型：
- 使用 class-type 以外的类型会导致错误。
- 使用 self、parent 或 static 都会导致错误。
DNF 类型：
- 如果使用了更通用的类型，则更加严格的那个类型就是多余的。
- 使用两个相同的交集类型。

注意: 不过它不能确保类型最小化，因为要达到这样的效果，还要加载使用类型的 class。

例如，假设 A 和 B 都是一个类的别名，而 A|B 仍然是有效的，哪怕它可以被简化为 A 或 B。同样的，如果 B extends A {}，那 A|B 仍然是有效的联合类型，尽管它可以被简化为 A。

<?php
function foo(): int|INT {} // 不允许
function foo(): bool|false {} // 不允许
function foo(): int&Traversable {} // 不允许
function foo(): self&Traversable {} // 不允许

use A as B;
function foo(): A|B {} // 不允许 ("use" 是名称解析的一部分)
function foo(): A&B {} // 不允许 ("use" 是名称解析的一部分)

class_alias('X', 'Y');
function foo(): X|Y {} // 允许 (运行时才能知道重复性)
function foo(): X&Y {} // 允许 (运行时才能知道重复性)
?>

示例

示例 #3 基础类类型声明

<?php
class C {}
class D extends C {}

// 没有继承 C。
class E {}

function f(C $c) {
    echo get_class($c)."\n";
}

f(new C);
f(new D);
f(new E);
?>

以上示例在 PHP 8 中的输出：

C
D

Fatal error: Uncaught TypeError: f(): Argument #1 ($c) must be of type C, E given, called in /in/gLonb on line 14 and defined in /in/gLonb:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
  thrown in - on line 8

示例 #4 基础接口类型声明

<?php
interface I { public function f(); }
class C implements I { public function f() {} }

// 没有实现（implement）I。
class E {}

function f(I $i) {
    echo get_class($i)."\n";
}

f(new C);
f(new E);
?>

以上示例在 PHP 8 中的输出：

C

Fatal error: Uncaught TypeError: f(): Argument #1 ($i) must be of type I, E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
  thrown in - on line 8

示例 #5 基础返回类型声明

<?php
function sum($a, $b): float {
    return $a + $b;
}

// Note that a float will be returned.
var_dump(sum(1, 2));
?>

以上示例会输出：

float(3)

示例 #6 返回对象

<?php
class C {}

function getC(): C {
    return new C;
}

var_dump(getC());
?>

以上示例会输出：

object(C)#1 (0) {
}

示例 #7 可为 null 参数类型声明

<?php
class C {}

function f(?C $c) {
    var_dump($c);
}

f(new C);
f(null);
?>

以上示例会输出：

object(C)#1 (0) {
}
NULL

示例 #8 可为 null 返回类型声明

<?php
function get_item(): ?string {
    if (isset($_GET['item'])) {
        return $_GET['item'];
    } else {
        return null;
    }
}
?>

示例 #9 类属性类型化声明

<?php
class User {
    public static string $foo = 'foo';

    public int $id;
    public string $username;

    public function __construct(int $id, string $username) {
        $this->id = $id;
        $this->username = $username;
    }
}
?>

严格类型

默认如果可能，PHP 会强制转化不合适的类型为想要的标量类型。比如，参数想要 string，传入的是 int，则会获取 string 类型的变量。

可以按文件开启严格模式。在严格模式下，只能接受完全匹配的类型，否则会抛出 TypeError。唯一的例外是 int 值也可以传入声明为 float 的类型。

警告

通过内部函数调用函数时，不会受 strict_types 声明影响。

要开启严格模式，使用 declare 开启 strict_types：

注意:
文件开启严格类型后的内部调用函数将应用严格类型，而不是在声明函数的文件内开启。如果文件没有声明开启严格类型，而被调用的函数所在文件有严格类型声明，那将遵循调用者的设置（开启类型强制转化），值也会强制转化。

注意:
只有为标量类型的声明开启严格类型。

示例 #10 参数值的严格类型

<?php
declare(strict_types=1);

function sum(int $a, int $b) {
    return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1.5, 2.5));
?>

以上示例在 PHP 8 中的输出：

int(3)

Fatal error: Uncaught TypeError: sum(): Argument #1 ($a) must be of type int, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
  thrown in - on line 4

示例 #11 参数值的类型强制转化

<?php
function sum(int $a, int $b) {
    return $a + $b;
}

var_dump(sum(1, 2));

// 以下会强制转化为整型，注意以下内容输出！
var_dump(sum(1.5, 2.5));
?>

以上示例会输出：

int(3)
int(3)

示例 #12 返回值的严格类型

<?php
declare(strict_types=1);

function sum($a, $b): int {
    return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1, 2.5));
?>

以上示例会输出：

int(3)

Fatal error: Uncaught TypeError: sum(): Return value must be of type int, float returned in -:5
Stack trace:
#0 -(9): sum(1, 2.5)
#1 {main}
  thrown in - on line 5

发现了问题？

了解如何改进此页面 • 提交拉取请求 • 报告一个错误

＋添加备注

用户贡献的备注 2 notes

down

toinenkayt (ta at ta) [iwonderr] gmail d ¶

3 years ago

While waiting for native support for typed arrays, here are a couple of alternative ways to ensure strong typing of arrays by abusing variadic functions. The performance of these methods is a mystery to the writer and so the responsibility of benchmarking them falls unto the reader.

PHP 5.6 added the splat operator (...) which is used to unpack arrays to be used as function arguments. PHP 7.0 added scalar type hints. Latter versions of PHP have further improved the type system. With these additions and improvements, it is possible to have a decent support for typed arrays.

<?php
declare (strict_types=1);

function typeArrayNullInt(?int ...$arg): void {
}

function doSomething(array $ints): void {
    (function (?int ...$arg) {})(...$ints);
    // Alternatively, 
    (fn (?int ...$arg) => $arg)(...$ints);
    // Or to avoid cluttering memory with too many closures
    typeArrayNullInt(...$ints);

    /* ... */
}

function doSomethingElse(?int ...$ints): void {
    /* ... */
}

$ints = [1,2,3,4,null];
doSomething ($ints);
doSomethingElse (...$ints);
?>

Both methods work with all type declarations. The key idea here is to have the functions throw a runtime error if they encounter a typing violation. The typing method used in doSomethingElse is cleaner of the two but it disallows having any other parameters after the variadic parameter. It also requires the call site to be aware of this typing implementation and unpack the array. The method used in doSomething is messier but it does not require the call site to be aware of the typing method as the unpacking is performed within the function. It is also less ambiguous as the doSomethingElse would also accept n individual parameters where as doSomething only accepts an array. doSomething's method is also easier to strip away if native typed array support is ever added to PHP. Both of these methods only work for input parameters. An array return value type check would need to take place at the call site.

If strict_types is not enabled, it may be desirable to return the coerced scalar values from the type check function (e.g. floats and strings become integers) to ensure proper typing.

down

crash ¶

3 years ago

The documentation lacks the information, that it's possible to change the return type of a method defined in an interface when the interface's methods return type is defined as `mixed`.

From the RFC:

"The mixed return type could be narrowed in a subclass as this is covariant and is allowed in LSP." (https://wiki.php.net/rfc/mixed_type_v2)

This means the following code is valid in PHP 8.0:

<?php

interface ITest
{
    public function apfel(): mixed; // valid as of 8.0
}

class Test implements ITest
{
    public function apfel(): array // more explicit
    {
        return [];
    }
}

var_dump((new Test())->apfel());
?>

You can see the result here: https://3v4l.org/PXDB6