assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assert断言检测

说明

assert(mixed $assertion, Throwable|string|null $description = null): bool

assert() 允许定义预期(expectations):在开发和测试环境中生效的断言,但在生产环境中会优化掉以达到零成本。

断言应该只用于调试功能。其中一个用例是检查健全性的前提条件,应该始终为 true,如果不满足这些条件,则表示存在某些编程错误。 另一个用例是确保某些功能的存在,例如扩展函数或某些系统限制和特性。

由于断言可以配置为已消除,因此应该用于普通运行时操作,比如检查输入参数。一般来说,代码应该在禁用断言检查的情况下仍然按预期运行。

assert() 将检查 assertion 中指定的预期(expectations)是否成立。如果不成立,也就是结果为 false,它将根据 assert() 的配置采取适当的操作。

assert() 的行为由以下 INI 设置决定:

断言 配置选项
名字 默认 说明 更新日志
zend.assertions 1
  • 1:生成并执行代码(开发模式)
  • 0:生成代码但在运行时跳转
  • -1:生成代码但在运行时跳转(生产模式)
 
assert.active true false 时,assert() 将不会检查预期(expectation)并且无条件返回 true 自 PHP 8.3.0 起弃用。
assert.callback null

当断言失败时,将调用用户定义的函数,其签名应该是:

assert_callback(
    string $file,
    int $line,
    null $assertion,
    string $description = ?
): void

在 PHP 8.0.0 之前,回调的签名应该是:

assert_callback(
    string $file,
    int $line,
    string $assertion,
    string $description = ?
): void

自 PHP 8.3.0 起弃用。
assert.exception true 如果为 true,则如果不能满足预期(expectations),将抛出 AssertionError 异常。 自 PHP 8.3.0 起弃用
assert.bail false true 时,如果预期(expectation)不支持,将会中止 PHP 脚本的执行。 自 PHP 8.3.0 起弃用
assert.warning true true 时,则如果预期(expectation)不支持,将发出 E_WARNING 警告。如果启用了 assert.exception,此 INI 设置将无效。 自 PHP 8.3.0 起弃用

参数

assertion

可以是任何带返回值的表达式,运行后的结果用于表示断言成功还是失败。

警告

在 PHP 8.0.0 之前,如果 assertionstring,将解释为 PHP 代码,并通过 eval() 执行。这个字符串将作为第三个参数传递给回调函数。这种行为在 PHP 7.2.0 中弃用,并在 PHP 8.0.0 中移除

description

如果 descriptionThrowable 的实例,只有在 assertion 执行失败时才会抛出。

注意:

自 PHP 8.0.0 开始,在调用可能定义的断言回调之前执行此操作。

注意:

自 PHP 8.0.0 开始,无论 assert.exception 的配置如何,都将会抛出该 object

注意:

自 PHP 8.0.0 开始,在这种情况下,assert.bail 设置不起作用。

如果 descriptionstring,当发出异常或警告时,将使用该消息。 如果 assertion 失败了,可选的 description 将会包括在失败信息里。

如果省略 description, 将在编译时创建默认 description,该 description 等于对 assert() 调用的源代码。

返回值

assert() 总是返回 true,前提是以下条件中至少有一个为真:

  • zend.assertions=0
  • zend.assertions=-1
  • assert.exception=1
  • assert.bail=1
  • 将自定义异常对象传递给 description

如果所有条件都不满足, assert() 将在 assertion 为真时返回 true,否则返回 false。urn true if assertion is truthy and false otherwise.

更新日志

版本 说明
8.3.0 弃用所有的 assert. INI 设置。
8.0.0 assert() 将不再对字符串参数求值,而是跟其他参数一样对待。应该使用 assert($a == $b) 替代 assert('$a == $b')。已移除 assert.quiet_eval php.ini 指令和 ASSERT_QUIET_EVAL 常量,因为它们不再有任何作用。
8.0.0 如果 descriptionThrowable 的实例,无论 assert.exception 的值如何,如果断言失败,该对象都会被抛出。
8.0.0 如果 descriptionThrowable 的实例,即使设置了用户回调,也不会调用该回调。
8.0.0 不再允许在命名空间中声明叫做 assert() 的函数,并发出 E_COMPILE_ERROR
7.3.0 弃用在命名空间中声明 assert() 函数。这样声明会发出 E_DEPRECATED
7.2.0 弃用使用 string 作为 assertion。当 assert.activezend.assertions 都设为 1 时,现在会发出 E_DEPRECATED 通知。

示例

示例 #1 assert() 示例

<?php
assert
(1 > 2);
echo
'Hi!';

如果启用断言(zend.assertions=1) 以上示例会输出:

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

如果禁用断言(zend.assertions=0zend.assertions=-1) 以上示例会输出:

Hi!

示例 #2 使用自定义信息

<?php
assert
(1 > 2, "Expected one to be greater than two");
echo
'Hi!';
?>

如果启用断言,以上示例会输出:

Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2
Stack trace:
#0 example.php(2): assert(false, 'Expected one to...')
#1 {main}
  thrown in example.php on line 2

如果禁用断言,以上示例会输出:

Hi!

示例 #3 使用自定义异常类

<?php
class ArithmeticAssertionError extends AssertionError {}

assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
echo
'Hi!';

如果启用断言,以上示例会输出:

Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4
Stack trace:
#0 {main}
  thrown in example.php on line 4

如果禁用断言,以上示例会输出:

Hi!

参见

add a note

User Contributed Notes

There are no user contributed notes for this page.
To Top