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.assertions1
    • 1：生成并执行代码（开发模式）
    • 0：生成代码但在运行时跳转
    • -1：生成代码但在运行时跳转（生产模式）
    		 
    assert.activetrue 为 false 时，assert() 将不会检查预期（expectation）并且无条件返回 true。 自 PHP 8.3.0 起弃用。
    assert.callbacknull

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

    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.exceptiontrue 如果为 true，则如果不能满足预期（expectations），将抛出 AssertionError 异常。 自 PHP 8.3.0 起弃用
    assert.bailfalse 为 true 时，如果预期（expectation）不支持，将会中止 PHP 脚本的执行。 自 PHP 8.3.0 起弃用
    assert.warningtrue 为 true 时，则如果预期（expectation）不支持，将发出 E_WARNING 警告。如果启用了 assert.exception，此 INI 设置将无效。 自 PHP 8.3.0 起弃用

    参数

    assertion

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

    警告

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

    description

    如果 description 是 Throwable 的实例，只有在 assertion 执行失败时才会抛出。

    注意:

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

    注意:

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

    注意:

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

    如果 description 是 string，当发出异常或警告时，将使用该消息。 如果 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.0assert() 将不再对字符串参数求值，而是跟其他参数一样对待。应该使用 assert($a == $b) 替代 assert('$a == $b')。已移除 assert.quiet_evalphp.ini 指令和 ASSERT_QUIET_EVAL 常量，因为它们不再有任何作用。
    8.0.0 如果 description 是 Throwable 的实例，无论 assert.exception 的值如何，如果断言失败，该对象都会被抛出。
    8.0.0 如果 description 是 Throwable 的实例，即使设置了用户回调，也不会调用该回调。
    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 通知。

    示例

    示例 #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=0 或 zend.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!

    参见

    To Top