assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assertassertion が false であるかどうかを調べる

説明

PHP 5 および PHP 7

assert(mixed $assertion, string $description = ?): bool

PHP 7

assert(mixed $assertion, Throwable $exception = ?): bool

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番目の引数を指定できます。これを設定すると、 descriptionassert() に渡せるようになります。

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 では、評価対象の文字列か、あるいは bool 値しか指定できませんでした。 PHP 7 ではそれ以外にも、値を返すあらゆる式を指定できます。 この式を実行した結果を用いて、アサーションに成功したか否かを判断します。

警告

assertionstring を使うのは PHP 7.2.0 以降は 推奨されなくなりました。 PHP 8.0.0 以降では 削除されています

description

オプションの説明です。 assertion が失敗したときのメッセージを設定します。 PHP 7 からは、この説明が指定されない場合、 assert() を呼び出したソースコードに関するデフォルトの説明が設定されます。

exception

PHP 7 では、第二パラメータに、文字列だけではなく Throwable オブジェクトを指定できるようになりました。 これを指定した場合は、 assert.exception が有効で かつアサーションに失敗した場合に、そのオブジェクトをスローします。

戻り値

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

変更履歴

バージョン 説明
8.0.0 assert() は、 文字列の引数を評価しなくなりました。 代わりに、他の引数と同じ扱いをされるようになっています。 assert('$a == $b') ではなく、 assert($a == $b) を使うべきです。 php.ini ディレクティブ assert.quiet_evalASSERT_QUIET_EVAL も削除されており、それらを使っても何も起きなくなっています。
8.0.0 名前空間の内部で、 assert() という名前の関数を宣言することはできなくなりました。 宣言した場合、E_COMPILE_ERROR が発生します。
7.3.0 名前空間の内部で、 assert() という名前の関数を宣言することは推奨されなくなりました。 宣言した場合、 E_DEPRECATED が発生するようになっています。
7.2.0 assertionstring を使うことは 推奨されなくなりました。 assert.activezend.assertions が 両方 1 に設定されると、 E_DEPRECATED レベルの警告が発生するようになりました。
7.0.0 assert() が言語構造となり、関数ではなくなりました。 assertion に式を指定できるようになりました。 第二パラメータは、 exception (Throwable オブジェクトを渡した場合) あるいは description (PHP 5.4.8 以降でサポートされていたもの) のいずれかであると解釈されるようになりました。

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

例1 失敗した assertion をカスタムハンドラで処理する

<?php
// assertを有効にし、出力を抑制する
assert_options(ASSERT_ACTIVE1);
assert_options(ASSERT_WARNING0);
assert_options(ASSERT_QUIET_EVAL1);

// ハンドラ関数を作成する
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_ACTIVE1);
assert_options(ASSERT_WARNING0);
assert_options(ASSERT_QUIET_EVAL1);

// ハンドラ関数を作成する
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

参考

関連キーワード:  assertion, assert, rt, 関数, 設定, exception, アサーション, assertions, 失敗, zend