Проверяет, является ли утверждение FALSE

Описание

PHP 5 и 7

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

PHP 7

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

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

Традиционная работа функции assert (PHP 5 и 7)

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

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

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

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

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

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

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

Ожидания (только PHP 7)

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

В то время как функция assert_options() может по-прежнему быть использована для контроля над поведением программы описанным выше образом, для обратной совместимости, но в PHP 7 код должен использовать две новые конфигурационные директивы для управления поведением assert() и не вызывать функцию assert_options().

Конфигурационные директивы PHP 7 для функции **assert()**
Директива	Значение по умолчанию	Возможные значения
zend.assertions	1	1: генерирует и выполняет код (режим разработки) 0: генерирует код, но перепрыгивает через него во время выполнения -1: не генерирует код (рабочий режим)
assert.exception	0	1: выбрасывает исключение, когда утверждение терпит неудачу, класса, предоставленного в параметре `exception`, либо класса AssertionError, если параметр `exception` не передан. 0: использует или создает экземпляр класса Throwable как описано выше, но только генерирует предупреждение на основе этого объекта, не выбрасывая его (для совместимости с поведением PHP 5)

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

assertion: Утверждение. В PHP 5 может быть строкой (string) для выполнения или логическим значением (boolean) для проверки. В PHP 7 это также может быть любое выражение, которое возвращает значение, которое будет выполнено, и результат использован для определения успешности проверки.

Внимание
Использование значения типа string в параметре assertion объявлено УСТАРЕВШИМ с PHP 7.2.
description: Необязательное описание, которое будет добавлено в сообщение, если проверка утверждения assertion будет провалена.
exception: В PHP 7 второй параметр может быть объектом Throwable вместо строки (string). Этот объект будет выбрасываться в случае неудачной проверки утверждения при включенной конфигурационной директиве assert.exception.

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

FALSE, если проверка провалена, TRUE в противном случае.

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

Версия	Описание
7.2.0	Использование строк в параметре `assertion` объявлено устаревшим и будет приводить к ошибкам уровня `E_DEPRECATED` в случае, когда и assert.active и zend.assertions установлены в значение 1.
7.0.0	assert() теперь языковая конструкция, а не функция. `assertion` теперь может быть выражением. Второй параметр теперь интерпретируется как исключение `exception` (если передан объект Throwable), или как описание `description`, поддерживаемое с версии PHP 5.4.8 и далее.
5.4.8	Добавлен параметр `description`. Параметр `description` также доступен в callback-функции в режиме `ASSERT_CALLBACK` в качестве четвертого аргумента.

Примеры

Традиционная работа функции assert (PHP 5 и 7)

Пример #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', 'Два больше чем один');
?>

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

 Неудачная проверка утверждения в test.php:21: 2 < 1
 Неудачная проверка утверждения в test.php:22: 2 < 1: Два больше чем один

Ожидания (только PHP 7)

Пример #3 Ожидания без собственного исключения


<?php
assert(true == false);
echo 'Привет!';
?>

При директиве zend.assertions, установленной в 0, данный код выведет:

Привет!

При директивах zend.assertions, установленной в 1 и assert.exception, установленной в 0, данный пример выведет:

Warning: assert(): assert(true == false) failed in - on line 2
Привет!

При директивах 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 Ожидания с собственным исключением


<?php
class CustomError extends AssertionError {}

assert(true == false, new CustomError('True не является false!'));
echo 'Привет!';
?>

При директиве zend.assertions, установленной в 0, данный код выведет:

Привет!

При директивах zend.assertions, установленной в 1 и assert.exception, установленной в 0, данный код выведет:

Warning: assert(): CustomError: True не является false! in -:4
Stack trace:
#0 {main} failed in - on line 4
Привет!

При директивах zend.assertions, установленной в 1 и assert.exception, установленной в 1, данный код выведет:

Fatal error: Uncaught CustomError: True не является false! in -:4
Stack trace:
#0 {main}
  thrown in - on line 4

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

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