PHP: assert - Manual

说明

PHP 5 和 7

assert(mixed $assertion, string $description = ?): bool

PHP 7

assert(mixed $assertion, Throwable $exception = ?): bool

assert() 会检查指定的 assertion 并在结果为 false 时采取适当的行动。

传统断言（PHP 5 和 7）

如果 assertion 是字符串，它将会被 assert() 当做 PHP 代码来执行。如果传入了 boolean 的条件作为 assertion，这个条件将不会显示为断言函数的参数；在调用你定义的 assert_options() 处理函数时，条件会转换为字符串，而布尔值 false 会被转换成空字符串。

断言这个功能应该只被用来调试。应该用于完整性检查时测试条件是否始终应该为 true，来指示某些程序错误，或者检查具体功能的存在（类似扩展函数或特定的系统限制和功能）。

断言不应该用于普通运行时操作，类似输入参数的检查。作为一个经验法则，在断言禁用时代码也应该能够正确地运行。

assert() 的行为可以通过 assert_options() 来配置，或者手册页面上描述的 .ini 设置。

assert_options() 和/或 ASSERT_CALLBACK 配置指令允许设置回调函数来处理失败的断言。

assert() 回调函数在构建自动测试套件的时候尤其有用，因为它们允许你简易地捕获传入断言的代码，并包含断言的位置信息。当信息能够被其他方法捕获，使用断言可以让它更快更方便！

回调函数应该接受三个参数。第一个参数包括了断言失败所在的文件。第二个参数包含了断言失败所在的行号，第三个参数包含了失败的表达式（如有任意 — 字面值例如 1 或者 "two" 将不会传递到这个参数）。PHP 5.4.8 及更高版本的用户也可以提供第四个可选参数，如果设置了，用于将 description 指定到 assert()。

Expectations（仅 PHP 7）

assert() 是 PHP 7 中的语言结构，允许定义 expectation：断言在开发和测试环境中生效，经过优化，在生产环境中零成本。

出于向后兼容的原因，assert_options() 仍然可以控制如上所述的行为。但仅限 PHP 7 的代码应使用两个新的配置指令来控制 assert() 的行为，而不是调用 assert_options()。

**用于 **assert()** 的 PHP 7 控制指令**
指令	默认值	可能值
zend.assertions	`1`	`1`：生成并执行代码（开发模式） `0`：生成代码但在运行时跳转 `-1`：生成代码但在运行时跳转（生产模式）
assert.exception	`0`	`1`：断言失败时抛出，抛出提供给 `exception` 的对象，或未提供 `exception` 时抛出新的 AssertionError 对象 `0`：如上所述使用/生成 Throwable，但仅仅是基于该对象生成警告而不是抛出（与 PHP 5 行为兼容）

参数

assertion: 断言。在 PHP 5 中，不是要求值的 string 就是要测试的 bool。自 PHP 7 起，可以是任何带返回值的表达式，运行后的结果用于表示断言成功还是失败。

警告
自 PHP 7.2.0 起弃用 string 作为 assertion，自 PHP 8.0.0 起删除。
description: 如果 assertion 失败了，选项 description 将会包括在失败信息里。自 PHP 7 起，如果没有提供 description，默认 description 将会提供调用 assert() 的源代码。
exception: 在 PHP 7 中，第二个参数可以是 Throwable 对象而不是 descriptive string，如果断言失败且启用 assert.exception 配置指令，会抛出该对象。

返回值

assertion 是 false 则返回 false，否则是 true。

更新日志

版本	说明
8.0.0	assert() 将不再对字符串参数求值，而是跟其他参数一样对待。应该使用 `assert($a == $b)` 替代 `assert('$a == $b')`。已移除 `assert.quiet_eval` `php.ini` 指令和 `ASSERT_QUIET_EVAL` 常量，因为它们不再有任何作用。
8.0.0	不再允许在命名空间中声明叫做 `assert()` 的函数，并发出 `E_COMPILE_ERROR`。
7.3.0	弃用在命名空间中声明 `assert()` 函数。这样声明会发出 `E_DEPRECATED`。
7.2.0	弃用使用 string 作为 `assertion`。当 assert.active 和 zend.assertions 都设为 `1` 时，现在会发出 `E_DEPRECATED` 通知。
7.0.0	assert() 现在是语言结构而不是函数。`assertion` 现在可以是表达式。第二个参数现在解释为 `exception`（如果给出了 Throwable），或者解释为自 PHP 5.4.8 开始支持的 `description`。

范例

传统断言（PHP 5 和 7）

示例 #1 使用自定义处理程序处理失败的断言


<?php
// 激活断言，并设置它为 quiet
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

//创建处理函数
function my_assert_handler($file, $line, $code)
{
    echo "<hr>Assertion Failed:
        File '$file'<br />
        Line '$line'<br />
        Code '$code'<br /><hr />";
}

// 设置回调函数
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// 让一则断言失败
assert('mysql_query("")');
?>

示例 #2 使用自定义处理器打印描述信息


<?php
// 激活断言，并设置它为 quiet
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// 创建处理函数
function my_assert_handler($file, $line, $code, $desc = null)
{
    echo "Assertion failed at $file:$line: $code";
    if ($desc) {
        echo ": $desc";
    }
    echo "\n";
}

// 设置回调
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Make an assertion that should fail
assert('2 < 1');
assert('2 < 1', 'Two is less than one');
?>

以上例程会输出：

 Assertion failed at test.php:21: 2 < 1
 Assertion failed at test.php:22: 2 < 1: Two is less than one

Expectations (PHP 7 only)

示例 #3 不带自定义异常的 Expectations


<?php
assert(true == false);
echo 'Hi!';
?>

zend.assertions 设为 0，以上示例会输出：

Hi!

zend.assertions 设为 1，assert.exception 设为 0，以上示例会输出：

Warning: assert(): assert(true == false) failed in - on line 2
Hi!

zend.assertions 和 assert.exception 都设为 1，以上示例会输出：

Fatal error: Uncaught AssertionError: assert(true == false) in -:2
Stack trace:
#0 -(2): assert(false, 'assert(true == ...')
#1 {main}
  thrown in - on line 2

示例 #4 包含自定义异常的 Expectations


<?php
class CustomError extends AssertionError {}

assert(true == false, new CustomError('True is not false!'));
echo 'Hi!';
?>

zend.assertions 设为 0，以上示例会输出：

Hi!

zend.assertions 设为 1，assert.exception 设为 0，以上示例会输出：

Warning: assert(): CustomError: True is not false! in -:4
Stack trace:
#0 {main} failed in - on line 4
Hi!

zend.assertions 和 assert.exception 都设为 1，以上示例会输出：

Fatal error: Uncaught CustomError: True is not false! in -:4
Stack trace:
#0 {main}
  thrown in - on line 4

参见

assert_options() - 设置/获取断言的各种标志

assert

说明

传统断言（PHP 5 和 7）

Expectations（仅 PHP 7）

参数

返回值

更新日志

范例

传统断言（PHP 5 和 7）

Expectations (PHP 7 only)

参见

User Contributed Notes