関数・クラス解説

assert

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

公式リファレンス

書式

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

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

説明

PHP 5 および PHP 7

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() は使わないようにしましょう。

パラメータ

assertion

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

警告 assertion に string を使うのは PHP 7.2 以降は 推奨されません

description

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

exception

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

返値

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

注意

警告 assertion に string を使うのは PHP 7.2 以降は 推奨されません

更新履歴

サンプル

従来のアサーション (PHP 5 および 7)
 
例1 失敗した assertion をカスタムハンドラで処理する
 

// 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 "
Assertion Failed:
        File '$file'
        Line '$line'
        Code '$code'";
}

// コールバックを設定する
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// 失敗するassertionを作成
assert('mysql_query("")');

 
例2 カスタムハンドラを使った説明の表示
 

// 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
 

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
 

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

参考

ワード検索

関数名アルファベット別

最終更新一覧

●stristr
　大文字小文字を区別せず文字列を検索し、ヒット箇所以降（あるいは以前）の文字列を返却

●stripslashes
　バックスラッシュでエスケープされた文字列から、バックスラッシュを取り除く

●stripos
　大文字小文字を区別せずに文字列が最初に現れる位置を取得する

●stripcslashes
　addcslashes() でクォートされた文字列をアンクォートする

●strip_tags
　文字列から HTML と PHP のタグを除去して返却

●strcspn
　指定した文字が最初に現れる位置を調べる

●strcoll
　ロケールに基づいて2つの文字列を比較し同じか（あるいは大小）を判定する

●strcmp
　2つの文字列を比較し同じか（あるいは大小）を判定する

●strchr
　strstr() のエイリアス

●strcasecmp
　2つの文字列を比較（大文字小文字を区別せず同じとみなす）

カテゴリー一覧

PHP の振る舞いの変更
音声フォーマットの操作
認証サービス
コマンドライン関連
圧縮およびアーカイブ
暗号
データベース関連
日付および時刻関連
ファイルシステム
自然言語および文字エンコーディング
画像処理および作成
メール関連
数学
テキスト以外の MIME 型
プロセス制御
その他の基本モジュール
その他のサービス
検索エンジン用の拡張モジュール
サーバー固有のモジュール
セッション関連
テキスト処理
変数・データ型関連
ウェブサービス
Windows 用のモジュール
XML 操作
GUI用の拡張モジュール