(PHP 4, PHP 5)
assert — assertion が FALSE であるかどうかを調べる
assert() は、指定した
assertion を調べて、結果が
FALSE の場合に適切な動作をします。
assertion が文字列として指定された場合、
assert()によりPHPコードとして評価されます。
文字列 assertionが優れているところは、
assertion のチェックがオフになった場合のオーバーヘッドがより少な
いことであり、assertionが失敗した場合のメッセージを式
assertionに有しています。
つまり、もし論理型の条件を 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()
に渡せるようになります。
assertion
アサーション。
description
オプションの説明で、
assertion が失敗したときのメッセージにこれを含めます。
アサーションが false となった場合に FALSE、それ以外の場合に TRUE を返します。
| バージョン | 説明 |
|---|---|
| 5.4.8 |
description パラメータが追加されました。
description はまた、
ASSERT_CALLBACK モードのコールバック関数の4番目の引数にも指定できるようになりました。
|
例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