assert
(PHP 4, PHP 5, PHP 7)
assert — assertion が false であるかどうかを調べる
説明
PHP 5 および PHP 7
assert
( mixed $assertion
[, string $description
] ) : bool
PHP 7
assert() は、指定した
assertion を調べて、結果が
false の場合に適切な動作をします。
従来のアサーション (PHP 5 および 7)
assertion が文字列として指定された場合、
assert()によりPHPコードとして評価されます。
もし論理型の条件を assertion として渡した場合、
assert_options() 関数で定義したであろう
アサーション関数への引数として表示されません。
その条件はハンドラ関数をコールする前に文字列に変換され、論理型の
false は空文字列に変換されます。
assertion は、デバッグ目的にのみ使用するべきです。
assertion を常にtrueとなる条件を調べる不具合診断に使用し、true
でない場合に何らかのプログラミングエラーを示したり、extension
関数または特定のシステム制限や機能といった、
特定の機能の存在をチェックするために使用することが可能です。
assersion は、入力パラメータのチェックのような通常の実行動作に 使用するべきではありません。一般的には、assertion のチェックを無効にしても そのコードが正常に動作しなければなりません。
assert() の動作は、 assert_options() またはマニュアルの関数の部分 に記述された .ini の設定により設定することが可能です。
関数 assert_options() や
ASSERT_CALLBACK 設定ディレクティブにより失敗した assertion
を処理するコールバック関数を設定することが可能です。
assert() のコールバックは、assertion が発生した場所に関する情報と共に assertion に渡されたコードを容易にキャプチャーできるため、 特に自動テストセットを構築する際に便利です。 この情報は他の手法でもキャプチャー可能ですが、assertion を使用することにより、より簡単かつ容易に行なうことが可能です!
コールバック関数は、3つの引数を受ける必要があります。最初の引数は、
assertionが失敗したファイルが含まれます。2番目の引数には、
assertionが失敗した行が含まれ、3番目の引数には失敗した式が含まれます
(もしある場合のみ。1 または "two" のようなリテラルの値は、
この引数に渡されません)。
PHP 5.4.8 以降では、オプションの4番目の引数を指定できます。これを設定すると、
description を assert()
に渡せるようになります。
Expectation (PHP 7 のみ)
assert() は PHP 7 で言語構造となり、expectation の定義を満たすようになりました。 すなわち、開発環境やテスト環境では有効であるが、運用環境では除去されて、まったくコストのかからないアサーションということです。
下位互換性を保つために、assert_options() でこれらの挙動を制御することもできますが、 PHP 7 以降でしか使わないコードでは、新たに導入された二つの設定ディレクティブを使って assert() の挙動を制御しましょう。 そして assert_options() は使わないようにしましょう。
| ディレクティブ | デフォルト値 | 取り得る値 |
|---|---|---|
| zend.assertions | 1
|
|
| assert.exception | 0
|
|
パラメータ
assertionアサーション。 PHP 5 では、評価対象の文字列か、あるいは bool 値しか指定できませんでした。 PHP 7 ではそれ以外にも、値を返すあらゆる式を指定できます。 この式を実行した結果を用いて、アサーションに成功したか否かを判断します。
警告
assertionに string を使うのは PHP 7.2 以降は 推奨されませんdescriptionオプションの説明です。
assertionが失敗したときのメッセージを設定します。 PHP 7 からは、この説明が指定されない場合、 assert() を呼び出したソースコードに関するデフォルトの説明が設定されます。exceptionPHP 7 では、第二パラメータに、文字列だけではなく Throwable オブジェクトを指定できるようになりました。 これを指定した場合は、 assert.exception が有効で かつアサーションに失敗した場合に、そのオブジェクトをスローします。
返り値
アサーションが false となった場合に false、それ以外の場合に true を返します。
変更履歴
| バージョン | 説明 |
|---|---|
| 7.2.0 | assertion に string を使うことは
推奨されなくなりました。
assert.active
と zend.assertions が
両方 |
| 7.0.0 | assert() が言語構造となり、関数ではなくなりました。
|
例
従来のアサーション (PHP 5 および 7)
例1 失敗した assertion をカスタムハンドラで処理する
<?php// assertを有効にし、出力を抑制する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');// 失敗するassertionを作成assert('mysql_query("")');?>
例2 カスタムハンドラを使った説明の表示
<?php// assertを有効にし、出力を抑制する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');// 失敗するassertionを作成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
Expectation (PHP 7 のみ)
例3 自作の例外を指定しない expectation
<?phpassert(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 が 1、かつ 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 自作の例外を用いた expectation
<?phpclass 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 が 1、かつ assert.exception が 1 の場合は、上の例の結果は次のようになります。
Fatal error: Uncaught CustomError: True is not false! in -:4
Stack trace:
#0 {main}
thrown in - on line 4
