<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: 0ece873cecfc4dacd14e8bebbec12c6e00de56a0 Maintainer: avenger Status: ready -->

<!-- CREDITS: mowangjuanzi, Luffy -->

<sect1 xml:id="language.types.declarations">

<title>类型声明</title>

<para>

类型声明可以用于函数的参数、返回值，

PHP 7.4.0 起还可以用于类的属性，

PHP 8.3.0 起还可以用于类的常量。

如果预期类型在调用时不匹配，则会抛出一个 <classname>TypeError</classname> 异常。

</para>

<para>

PHP 支持各种单一类型，除了 <type>resource</type>

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

</para>

<note>

<para>

当类实现了接口方法或者重新实现了父级类中定义的方法时，必须与上述定义兼容。如果方法遵循<link

linkend="language.oop5.variance">方差</link>规则，则兼容该方法。

</para>

</note>

<sect2 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.3.0</entry>

<entry>

新增了对类、接口、trait 和枚举常量类型的支持。

</entry>

</row>

<row>

<entry>8.2.0</entry>

<entry>

新增对 <acronym>DNF</acronym> 类型的支持。

</entry>

</row>

<row>

<entry>8.2.0</entry>

<entry>

新增对 literal 类型 <type>true</type> 的支持。

</entry>

</row>

<row>

<entry>8.2.0</entry>

<entry>

现在可以单独使用 <type>null</type> 和 <type>false</type>。

</entry>

</row>

<row>

<entry>8.1.0</entry>

<entry>

新增对交集类型的支持。

</entry>

</row>

<row>

<entry>8.1.0</entry>

<entry>

弃用 <type>void</type> 函数通过引用返回。

</entry>

</row>

<row>

<entry>8.1.0</entry>

<entry>

新增对返回类型 <acronym>never</acronym> 的支持。

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

新增对 <acronym>mixed</acronym> 类型的支持。

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

新增对返回类型 <acronym>static</acronym> 的支持。

</entry>

</row>

<row>

<entry>8.0.0</entry>

<entry>

新增对联合类型的支持。

</entry>

</row>

<row>

<entry>7.4.0</entry>

<entry>

新增对类属性类型化的支持。

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

新增对 <acronym>object</acronym> 类型的支持。

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

新增对 <acronym>iterable</acronym> 类型的支持。

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

新增对 <acronym>void</acronym> 类型的支持。

</entry>

</row>

<row>

<entry>7.1.0</entry>

<entry>

新增对可为 null 类型的支持。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</sect2>

<sect2 xml:id="language.types.declarations.base">

<title>原子类型使用说明</title>

<simpara>

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

</simpara>

<sect3 xml:id="language.types.declarations.base.scalar">

<title>标量类型</title>

<warning>

<para>

标量类型（<type>bool</type>、<type>int</type>、<type>float</type>、<type>string</type>）不支持别名。别名反而会视为类或接口名。例如，使用

<literal>boolean</literal> 作为类型声明，将要求值是 &instanceof; 类或接口

<literal>boolean</literal>，而不是类型

<type>bool</type>。

</para>

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

function test(boolean $param) {}

test(true);

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

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

]]>

</screen>

</informalexample>

</warning>

</sect3>

<sect3 xml:id="language.types.declarations.void">

<title>void</title>

<note>

<para>

从 PHP 8.1.0 起弃用 <type>void</type> 函数通过引用返回，因为这样的函数自相矛盾。在此之前调用时总是会发出如下

<constant>E_NOTICE</constant>：<computeroutput>Only variable references should be returned by reference</computeroutput>。

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

function &test(): void {}

?>

]]>

</programlisting>

</informalexample>

</para>

</note>

</sect3>

<sect3 xml:id="language.types.declarations.base.function">

<title>Callable 类型</title>

<para>

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

</para>

<note>

<simpara>

无法指定函数的签名。

</simpara>

</note>

</sect3>

<sect3 xml:id="language.types.declarations.references">

<title>通过引用传递的参数类型</title>

<simpara>

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

</simpara>

<example>

<title>通过引用传递的参数类型</title>

<programlisting role="php">

<![CDATA[

<?php

function array_baz(array &$param)

{

$param = 1;

}

$var = [];

array_baz($var);

var_dump($var);

array_baz($var);

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

</sect3>

</sect2>

<sect2 xml:id="language.types.declarations.composite">

<title>复合类型使用说明</title>

<para>

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

</para>

<caution>

<simpara>

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

</simpara>

</caution>

<sect3 xml:id="language.types.declarations.composite.union">

<title>联合类型</title>

<warning>

<simpara>

在一个联合类型中不能同时用两个单例类型 <type>false</type> 和

<type>true</type>。而是使用 <type>bool</type> 替代。

</simpara>

</warning>

<caution>

<simpara>

在 PHP 8.2.0 之前，由于 <type>false</type> 和 <type>null</type>

不能作为独立的类型使用，因此不允许仅由这些类型组成联合类型。这还包括以下类型：<type>false</type>、<literal>false|null</literal>,

和 <literal>?false</literal>。

</simpara>

</caution>

<sect4 xml:id="language.types.declarations.nullable">

<title>可为 null 类型语法糖</title>

<para>

单个基本类型声明可以通过在类型前添加问号（<literal>?</literal>）来标记可为 null。因此

<literal>?T</literal> 和 <literal>T|null</literal> 是相同的。

</para>

<note>

<simpara>

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

</simpara>

</note>

<note>

<para>

也可以通过设置参数的参数的默认值为 <literal>null</literal> 来实现允许为

null。但并不建议这么做，因为如果在子类中更改了默认值，会引发类型兼容冲突，需要将

<type>null</type> 类型添加到类型声明中。

此行为在 PHP 8.4 中也被弃用。

</para>

<example>

<title>使参数可以为 null 的旧方法</title>

<programlisting role="php">

<![CDATA[

<?php

class C {}

function f(C $c = null) {

var_dump($c);

}

f(new C);

f(null);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

object(C)#1 (0) {

}

NULL

]]>

</screen>

</example>

</note>

</sect4>

</sect3>

<sect3 xml:id="language.types.declarations.composite.redundant">

<title>重复冗余的类型</title>

<para>

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

<itemizedlist>

<listitem>

<simpara>

解析出来的类型只能出现一次。例如这样的类型 <literal>int|string|INT</literal> 或

<literal>Countable&amp;Traversable&amp;COUNTABLE</literal> 会导致错误。

</simpara>

</listitem>

<listitem>

<simpara>

使用 <type>mixed</type> 或 <type>never</type> 会导致错误。

</simpara>

</listitem>

<listitem>

<simpara>对于联合类型：</simpara>

<itemizedlist>

<listitem>

<simpara>

使用了 <type>bool</type> 时就不能再附带使用 <type>false</type> 或者 <type>true</type>。

</simpara>

</listitem>

<listitem>

<simpara>

使用了 <type>object</type> 时就不能再附带使用 class 类型。

</simpara>

</listitem>

<listitem>

<simpara>

使用了 <type>iterable</type> 时，不能再附带使用 <type>array</type>

和 <classname>Traversable</classname>。

</simpara>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<simpara>对于交集类型：</simpara>

<itemizedlist>

<listitem>

<simpara>

使用 class-type 以外的类型会导致错误。

</simpara>

</listitem>

<listitem>

<simpara>

使用 <type>self</type>、<type>parent</type>

或 <type>static</type> 都会导致错误。

</simpara>

</listitem>

</itemizedlist>

</listitem>

<listitem>

<simpara><acronym>DNF</acronym> 类型：</simpara>

<itemizedlist>

<listitem>

<simpara>

如果使用了更通用的类型，则更加严格的那个类型就是多余的。

</simpara>

</listitem>

<listitem>

<simpara>

使用两个相同的交集类型。

</simpara>

</listitem>

</itemizedlist>

</listitem>

</itemizedlist>

</para>

<note>

<simpara>

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

</simpara>

</note>

<para>

例如，假设 <literal>A</literal> 和 <literal>B</literal> 都是一个类的别名，

而 <literal>A|B</literal> 仍然是有效的，哪怕它可以被简化为

<literal>A</literal> 或

<literal>B</literal>。

同样的，如果 <code>B extends A {}</code>，那 <literal>A|B</literal>

仍然是有效的联合类型，尽管它可以被简化为

<literal>A</literal>。

<informalexample>

<programlisting role="php">

<![CDATA[

<?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 {} // 允许 (运行时才能知道重复性)

?>

]]>

</programlisting>

</informalexample>

</para>

</sect3>

</sect2>

<sect2 xml:id="language.types.declarations.examples">

&reftitle.examples;

<example>

<title>基础类类型声明</title>

<programlisting role="php">

<![CDATA[

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

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

<example>

<title>基础接口类型声明</title>

<programlisting role="php">

<![CDATA[

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

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

<example>

<title>基础返回类型声明</title>

<programlisting role="php">

<![CDATA[

<?php

function sum($a, $b): float {

return $a + $b;

}

// Note that a float will be returned.

var_dump(sum(1, 2));

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

float(3)

]]>

</screen>

</example>

<example>

<title>返回对象</title>

<programlisting role="php">

<![CDATA[

<?php

class C {}

function getC(): C {

return new C;

}

var_dump(getC());

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

object(C)#1 (0) {

}

]]>

</screen>

</example>

<example>

<title>可为 null 参数类型声明</title>

<programlisting role="php">

<![CDATA[

<?php

class C {}

function f(?C $c) {

var_dump($c);

}

f(new C);

f(null);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

object(C)#1 (0) {

}

NULL

]]>

</screen>

</example>

<example>

<title>可为 null 返回类型声明</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

function get_item(): ?string {

if (isset($_GET['item'])) {

return $_GET['item'];

} else {

return null;

}

}

?>

]]>

</programlisting>

</example>

<example>

<title>类属性类型化声明</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

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

}

}

?>

]]>

</programlisting>

</example>

</sect2>

<!-- TODO Move this into its own declare page -->

<sect2 xml:id="language.types.declarations.strict">

<title>严格类型</title>

<para>

默认如果可能，PHP 会强制转化不合适的类型为想要的标量类型。

比如，参数想要 <type>string</type>，传入的是 <type>int</type>，

则会获取 <type>string</type> 类型的变量。

</para>

<para>

可以按文件开启严格模式。

在严格模式下，只能接受完全匹配的类型，否则会抛出 <classname>TypeError</classname>。

唯一的例外是 <type>int</type> 值也可以传入声明为 <type>float</type> 的类型。

</para>

<warning>

<simpara>

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

</simpara>

</warning>

<para>

要开启严格模式，使用 &declare; 开启

<literal>strict_types</literal>：

</para>

<note>

<para>

文件开启严格类型后的<emphasis>内部</emphasis>调用函数将应用严格类型，

而不是在声明函数的文件内开启。

如果文件没有声明开启严格类型，而被调用的函数所在文件有严格类型声明，

那将遵循调用者的设置（开启类型强制转化），

值也会强制转化。

</para>

</note>

<note>

<para>

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

</para>

</note>

<example>

<title>参数值的严格类型</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

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

?>

]]>

</programlisting>

&example.outputs.8;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

<example>

<title>参数值的类型强制转化</title>

<programlisting role="php">

<![CDATA[

<?php

function sum(int $a, int $b) {

return $a + $b;

}

var_dump(sum(1, 2));

// 以下会强制转化为整型，注意以下内容输出！

var_dump(sum(1.5, 2.5));

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

int(3)

int(3)

]]>

</screen>

</example>

<example>

<title>返回值的严格类型</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

declare(strict_types=1);

function sum($a, $b): int {

return $a + $b;

}

var_dump(sum(1, 2));

var_dump(sum(1, 2.5));

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

</sect2>

</sect1>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->