説明
bool assert(mixed $assertion, Throwablestringnull $description = null)
アサーションは、デバッグ目的にのみ使用するべきです。
アサーションを常に true となる条件を調べる不具合診断に使用し、
true でない場合に何らかのプログラミングエラーを示したり、
extension 関数または特定のシステム制限や機能といった、
特定の機能の存在をチェックするために使用することが可能です。
アサーションは削除するように設定できるため、
入力パラメータのチェックのような通常の実行動作に使用するべきでは
ありません。
一般的には、アサーションのチェックを無効にしてもそのコードが正常に動作しなければなりません。
assert は
assertion で指定された
expectation をチェックします。
それを満たさない場合、この関数の結果は false になり、
assert の設定に応じて適切な動作をします。
assert の振る舞いは、以下のINI設定によって制御できます:
Assert 設定オプション
| 名前 |
デフォルト |
説明 |
変更履歴 |
| zend.assertions |
1 |
-
1: コードを生成して実行する (開発モード)
-
0: コードを生成するが、実行時には読み飛ばす
-
-1: コードを生成しない (運用モード)
|
|
| assert.active |
true |
false を指定すると、
assert は expectation をチェックせず、
無条件に true を返します。
|
PHP 8.3.0 以降は非推奨
|
| assert.callback |
null |
アサーションが失敗した時にコールされるユーザー定義の関数。
シグネチャは以下の形であるべきです:
void assert_callback(
string $file,
int $line,
null $assertion,
string $description = ?
)
|
PHP 8.0.0 より前のバージョンでは、
コールバックのシグネチャは以下の形であるべきでした:
void assert_callback(
string $file,
int $line,
string $assertion,
string $description = ?
)
PHP 8.3.0 以降は非推奨
|
| assert.exception |
true |
true を指定すると、expectation を満たさない場合に
AssertionError がスローされます。
|
PHP 8.3.0 以降は非推奨
|
| assert.bail |
false |
true を指定すると、expectation を満たさない場合に
PHP スクリプトの実行を停止します。
|
PHP 8.3.0 以降は非推奨
|
| assert.warning |
true |
true を指定すると、expectation を満たさない場合に
E_WARNING が発生します。
このINI設定は
assert.exception
が有効な場合は意味がありません。
|
PHP 8.3.0 以降は非推奨
|
パラメータ
-
assertion
-
値を返すあらゆる式を指定できます。
この式を実行した結果を用いて、アサーションに成功したか否かを判断します。
警告
PHP 8.0.0 より前のバージョンでは、
assertion に文字列を指定すると、
PHP コードとして解釈され、
eval 経由で実行されていました。
この文字列はコールバックの3番目の引数として渡されていました。
この振る舞いは 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 が文字列の場合、
例外や警告が発生した場合にここで指定したメッセージを使います。
assertion
が失敗したときのオプションのメッセージを指定します。
description は省略できます。
デフォルトの値は、assert
を呼び出したソースコードと同じです。この値はコンパイル時に生成されます。
戻り値
assert は、以下のうちのひとつが当てはまる場合、常に true を返します:
zend.assertions=0zend.assertions=-1assert.exception=1assert.bail=1- カスタムの例外オブジェクトが
description に渡された場合
上記の条件がすべて当てはまらない場合でも、
assertion が真と評価できる値であれば true を返します。
そうでない場合、false を返します。
例
例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) 場合は、上の例の結果は次のようになります:
例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
アサーションが無効になっている場合は、上の例の結果は次のようになります:
例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
アサーションが無効になっている場合は、上の例の結果は次のようになります: