# assert

(PHP 4, PHP 5, PHP 7)

assert — 检查一个断言是否为 `FALSE`

### 说明

PHP 5

assert ( mixed `$assertion` [, string `$description` ] ) : bool

PHP 7

assert ( mixed `$assertion` [, Throwable `$exception` ] ) : bool

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

#### Traditional assertions (PHP 5 and 7)

如果 `assertion` 是字符串，它将会被 assert() 当做 PHP 代码来执行。 `assertion` 是字符串的优势是当禁用断言时它的开销会更小，并且在断言失败时消息会包含 `assertion` 表达式。 这意味着如果你传入了 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 only)

assert() is a language construct in PHP 7, allowing for the definition of expectations: assertions that take effect in development and testing environments, but are optimised away to have zero cost in production.

While assert_options() can still be used to control behaviour as described above for backward compatibility reasons, PHP 7 only code should use the two new configuration directives to control the behaviour of assert() and not call assert_options().

PHP 7 configuration directives for assert()
Directive | Default value | Possible values
--- | --- | ---
zend.assertions | 1 | 1: generate and execute code (development mode) 0: generate code but jump around it at runtime -1: do not generate code (production mode)
assert.exception | 0 | 1: throw when the assertion fails, either by throwing the object provided as the `exception` or by throwing a new AssertionError object if `exception` wasn't provided 0: use or generate a Throwable as described above, but only generate a warning based on that object rather than throwing it (compatible with PHP 5 behaviour)

### 参数

`assertion`

  断言。In PHP 5, this must be either a string to be evaluated or a boolean to be tested. In PHP 7, this may also be any expression that returns a value, which will be executed and the result used to indicate whether the assertion succeeded or failed.

`description`

  如果 `assertion` 失败了，选项 description 将会包括在失败信息里。

`exception`

  In PHP 7, the second parameter can be a Throwable object instead of a descriptive string, in which case this is the object that will be thrown if the assertion fails and the assert.exception configuration directive is enabled.

### 返回值

assertion 是 false 则返回 `FALSE`，否则是 `TRUE`。

### 更新日志

版本 | 说明
--- | ---
7.0.0 | assert() is now a language construct and not a function. assertion() can now be an expression. The second parameter is now interpreted either as an `exception` (if a Throwable object is given), or as the `description` supported from PHP 5.4.8 onwards.
5.4.8 | 增加了参数 `description`。 `description` 现在也作为第四个参数提供给 `ASSERT_CALLBACK` 模式里的回调函数。

### 范例

#### Traditional assertions (PHP 5 and 7)

Example #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("")');
    ?>

Example #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)

Example #3 Expectations without a custom exception

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

With zend.assertions set to 0, the above example will output:

    Hi!

With zend.assertions set to 1 and assert.exception set to 0, the above example will output:

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

With zend.assertions set to 1 and assert.exception set to 1, the above example will output:

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

Example #4 Expectations with a custom exception

    <?php
    class CustomError extends AssertionError {}

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

With zend.assertions set to 0, the above example will output:

    Hi!

With zend.assertions set to 1 and assert.exception set to 0, the above example will output:

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

With zend.assertions set to 1 and assert.exception set to 1, the above example will output:

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

### 参见

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