assert

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

    assert — 检查断言

    描述

    assert(混合 $assertion, Throwable|字符串|null $description = null): 布尔值

    assert() 允许定义期望：在开发和测试环境中生效的断言，但在生产环境中被优化为零成本。

    断言应该仅用作调试功能。它们的一种用例是充当对始终应为 true 的先决条件的健全性检查，如果它们不成立，则表明存在一些编程错误。另一个用例是确保某些功能的存在，例如扩展函数或某些系统限制和功能。

    由于断言可以配置为消除，因此不应将其用于正常的运行时操作，例如输入参数检查。作为经验法则，即使断言检查被禁用，代码也应该按预期执行。

    assert() 将检查 assertion 中给出的期望是否成立。如果否，因此结果为 false，它将根据 assert() 的配置方式采取适当的措施。

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

    断言配置选项
    名称 默认值 描述 变更日志
    zend.assertions 1
    • 1：生成并执行代码（开发模式）
    • 0：生成代码，但在运行时跳过它
    • -1：不生成代码（生产模式）
    		  
    assert.active true 如果为 false，assert() 不检查期望，并无条件返回 true。 从 PHP 8.3.0 开始弃用。
    assert.callback null

    断言失败时要调用的用户定义函数。它的签名应该是

    assert_callback(
        字符串 $file,
        整数 $line,
        null $assertion,
        字符串 $description = ?
    ): void

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

    assert_callback(
        字符串 $file,
        整数 $line,
        字符串 $assertion,
        字符串 $description = ?
    ): void

    从 PHP 8.3.0 开始弃用。
    assert.exception true 如果为 true，如果期望不成立，则会抛出 AssertionError。 从 PHP 8.3.0 开始弃用。
    assert.bail false 如果为 true，如果期望不成立，则会中止 PHP 脚本的执行。 从 PHP 8.3.0 开始弃用。
    assert.warning true 如果为 true，如果期望不成立，则会发出 E_WARNING。如果 assert.exception 启用，则此 INI 设置无效。 从 PHP 8.3.0 开始弃用。

    参数

    assertion

    这是任何返回值的表达式，它将被执行，结果将用于指示断言是否成功或失败。

    警告

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

    description

    如果 description 是 Throwable 的实例，则仅当 assertion 被执行并失败时，才会抛出它。

    注意:

    从 PHP 8.0.0 开始，这在调用可能已定义的断言回调之前完成。

    注意:

    从 PHP 8.0.0 开始，无论 assert.exception 的配置如何，都会抛出 对象。

    注意:

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

    如果 description 是 字符串，如果发出异常或警告，将使用此消息。如果 assertion 失败，则将包含在失败消息中的可选描述。

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

    返回值

    assert() 将始终返回 true，如果以下至少一项为真

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

    如果所有条件都不成立，则如果 assertion 为真，则 assert() 将返回 true，否则返回 false。

    变更日志

    版本 描述
    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 如果 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 将 字符串 用作 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, "预期 1 大于 2");
    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("预期 1 大于 2"));
    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!

    参见

    改进此页面

    了解如何改进此页面 • 提交拉取请求 • 报告错误
    ＋添加注释

    用户贡献的注释 2 个注释

    31
    hodgman at ali dot com dot au
    16 年前
    如维基百科所述 - “断言主要是一种开发工具，在程序发布到公众时通常会被禁用。” 以及“断言应用于记录逻辑上不可能的情况并发现编程错误 - 如果出现‘不可能’的情况，则很明显存在严重错误。 这与错误处理不同：大多数错误条件都是可能的，尽管有些在实践中极不可能发生。 将断言用作通用错误处理机制通常不明智：断言不允许从错误中优雅地恢复，并且断言失败通常会突然停止程序执行。 断言也不显示用户友好的错误消息。”

    这意味着“gk at proliberty dot com” 给出的强制启用断言（即使它们已被手动禁用）的建议违背了仅将断言用作开发工具的最佳实践。
    8
    sven at rtbg dot de
    5 个月前
    随着 PHP 8.3 中的当前更改（弃用影响断言的 INI 设置）以及越来越多的开源库使用 `assert()` 作为一种简单的方法来确保 PHP 核心函数调用的模糊返回值确实不会被触发（例如，没有返回 NULL 或 FALSE，而是返回有用的值），关于断言仅作为开发时使用的工具的评论应该被认为是无效的。

    此外，静态代码分析工具使用从 `assert($x instanceof MyClass)` 获取的知识来了解可能的类型。

    断言正在生产代码中积极使用，它们非常有用，禁用它们只会带来很小的性能优势，因为断言表达式通常非常小。

    在适用时使用此工具！
    ＋添加注释
    To Top