assertion が FALSE であるかどうかを調べる

説明

PHP 5 および PHP 7

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

PHP 7

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

assert() は、指定した assertion を調べて、結果が FALSE の場合に適切な動作をします。

従来のアサーション (PHP 5 および 7)

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() に渡せるようになります。

Expectation (PHP 7 のみ)

assert() は PHP 7 で言語構造となり、expectation の定義を満たすようになりました。すなわち、開発環境やテスト環境では有効であるが、運用環境では除去されて、まったくコストのかからないアサーションということです。

下位互換性を保つために、assert_options() でこれらの挙動を制御することもできますが、 PHP 7 以降でしか使わないコードでは、新たに導入された二つの設定ディレクティブを使って assert() の挙動を制御しましょう。そして assert_options() は使わないようにしましょう。

**PHP 7 における **assert()** 用の設定ディレクティブ**
ディレクティブ	デフォルト値	取り得る値
zend.assertions	1	1: コードを生成して実行する (開発モード) 0: コードを生成するが、実行時には読み飛ばす -1: コードを生成しない (運用モード)
assert.exception	0	1: アサーションに失敗した場合には、 `exception` で指定したオブジェクトをスローするか、 `exception` を指定していない場合は AssertionError オブジェクトをスローします。 0: 先述の Throwable を使ったり生成したりしますが、そのオブジェクト上で警告を生成するだけであり、スローしません (PHP 5 と互換性のある挙動です)。

パラメータ

assertion: アサーション。 PHP 5 では、評価対象の文字列か、あるいは boolean 値しか指定できませんでした。 PHP 7 ではそれ以外にも、値を返すあらゆる式を指定できます。この式を実行した結果を用いて、アサーションに成功したか否かを判断します。
description: オプションの説明で、 assertion が失敗したときのメッセージにこれを含めます。
exception: PHP 7 では、第二パラメータに、文字列だけではなく Throwable オブジェクトを指定できるようになりました。これを指定した場合は、 assert.exception が有効でかつアサーションに失敗した場合に、そのオブジェクトをスローします。

返り値

アサーションが false となった場合に FALSE、それ以外の場合に TRUE を返します。

変更履歴

バージョン	説明
7.0.0	assert() が言語構造となり、関数ではなくなりました。 assertion() に式を指定できるようになりました。第二パラメータは、 `exception` (Throwable オブジェクトを渡した場合) あるいは `description` (PHP 5.4.8 以降でサポートされていたもの) のいずれかであると解釈されるようになりました。
5.4.8	`description` パラメータが追加されました。 `description` はまた、 `ASSERT_CALLBACK` モードのコールバック関数の4番目の引数にも指定できるようになりました。

例

従来のアサーション (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


<?php
assert(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


<?php
class 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

参考

assert_options() - 様々な assert フラグを設定/取得する