Проверка утверждения (равен ли результат FALSE)


(PHP 4, PHP 5)

assertПроверка утверждения (равен ли результат FALSE)

Описание

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

assert() проверит заданное утверждение assertion и совершит соответствующее действие, если результатом проверки окажется FALSE.

Если assertion задается в виде строки, оно будет рассматриваться функцией assert() как PHP код. Представление assertion в виде строки имеет свои преимущества. Во-первых, выключение проверки утверждений снижает накладные расходы. Во-вторых, сообщения о провале проверки будут содержать само утверждение assertion. То есть, если передать в качестве assertion какое-либо условное выражение, это условие невозможно будет получить в явном виде, в котором оно передавалось в проверяющую функцию, которую вы возможно определили с помощью assert_options(). Это условное выражение будет вычислено и преобразовано в строку до вызова проверяющей функции, соответственно логическое FALSE будет фигурировать в сообщении как пустая строка.

Утверждения должны использоваться только в целях отладки. Их можно использовать для тестирования каких-то условий, которые в штатных ситуациях всегда принимают значение TRUE, обратное должно указывать на программные ошибки. Также их можно использовать, чтобы удостовериться в наличии каких-либо расширений или системных ограничений.

Утверждения не должны использоваться в обычных операциях, таких как проверка входных параметров. Скрипт должен корректно выполняться, если отключить проверку утверждений.

Поведение функции assert() можно изменять с помощью функции assert_options() или заданием .ini-настроек.

Функция assert_options() и директива ASSERT_CALLBACK позволяют задать callback-функцию, которая будет вызываться при провале проверки утверждения.

Возможность вызывать callback-функции из assert() может быть полезна для создания автоматизированных тестовых пакетов. Посредством этих функций можно извлекать код, переданный на проверку вместе с информацией о том, где эта проверка была осуществлена. Подобную информацию можно получить и другими методами, однако использование утверждений быстрей и проще.

Callback-функция должна принимать три аргумента. Первый аргумент должен содержать файл, в котором утверждение не прошло проверку. Второй аргумент отвечает за номер строки в этом файле. В третьем аргументе будет передаваться выражение, содержащее ошибку (если таких несколько, строковые значение, вроде 1 или "два" не будут передаваться через этот аргумент). Пользователи PHP версий 5.4.8 и выше могут задать четвертый необязательный аргумент description, который будет также передан в функцию assert().

Список параметров

assertion

Утверждение.

description

Дополнительное описание, которое будет включено в сообщение об ошибке, если проверка assertion завершится неудачей.

Возвращаемые значения

FALSE в случае провала проверки, TRUE в остальных случаях.

Список изменений

Версия Описание
5.4.8 Добавлен аргумент description. Также description передается четвертым аргументом в callback-функцию в режиме ASSERT_CALLBACK.

Примеры

Пример #1 Обработка ошибочного утверждения пользовательским обработчиком

<?php
// Активируем проверку утверждений и сделаем его фоновым
assert_options(ASSERT_ACTIVE1);
assert_options(ASSERT_WARNING0);
assert_options(ASSERT_QUIET_EVAL1);

// Создадим функцию обработчик
function my_assert_handler($file$line$code)
{
    echo 
"<hr>Проверка утвеждения провалена:
        Файл '
$file'<br />
        Строка '
$line'<br />
        Код '
$code'<br /><hr />";
}

// Зададим callback-функцию
assert_options(ASSERT_CALLBACK'my_assert_handler');

// Создадим заведомо неверную команду
assert('mysql_query("")');
?>

Пример #2 Использование пользовательского обработчика для вывода описания ошибки

<?php
// Активируем утверждение и переводим в тихий режим
assert_options(ASSERT_ACTIVE1);
assert_options(ASSERT_WARNING0);
assert_options(ASSERT_QUIET_EVAL1);

// Создаем обработчик
function my_assert_handler($file$line$code$desc null)
{
    echo 
"Проверка завершилась неудачей в $file:$line$code";
    if (
$desc) {
        echo 
": $desc";
    }
    echo 
"\n";
}

// Задаем callback-функцию
assert_options(ASSERT_CALLBACK'my_assert_handler');

// Спровоцируем ошибку для проверки
assert('2 < 1');
assert('2 < 1''Два меньше одного');
?>

Результат выполнения данного примера:

 Assertion failed at test.php:21: 2 < 1 Assertion failed at test.php:22: 2 < 1: Два меньше одного 

Смотрите также

  • assert_options() - Установка/получение различных установок проверки утверждений