(PHP 4, PHP 5)
assert — Проверка утверждения (равен ли результат FALSE)
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_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);
// Создадим функцию обработчик
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_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);
// Создаем обработчик
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: Два меньше одного