Проверяет утверждение

Описание

assert(mixed $assertion, Throwable|string|null $description = null): bool

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

Утверждения следует использовать только в качестве отладочной функции. Один из вариантов их использования - проверка на вменяемость предварительных условий, которые всегда должны быть true и если они не выполняются, это указывает на ошибки программирования. Другой случай использования - убедиться в наличии определённых возможностей, например, функций модуля или определённых ограничений и возможностей системы.

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

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

Поведение конструкции assert() определяется следующими настройками INI:

**Опции настройки конструкции assert**
Имя	По умолчанию	Описание	Список изменений
zend.assertions	`1`	`1`: генерирует и выполняет код (режим разработки) `0`: генерирует код, но перепрыгивает через него во время выполнения `-1`: не генерирует код (рабочий режим)
assert.active	`true`	Если `false`, assert() не проверяет ожидание и возвращает `true`, безоговорочно.
assert.callback	`null`	Определяемая пользователем функция, вызываемая в случае неудачной проверки утверждения. Её сигнатура должна быть следующей: assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void	До PHP 8.0.0 сигнатура callback-функции должна быть: assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void
assert.exception	`true`	Если `true`, будет выброшена ошибка AssertionError в случае неудачной проверки утверждения.
assert.bail	`false`	Если `true`, выполнение PHP-скрипта прервётся в случае неудачной проверки утверждении.
assert.warning	`true`	Если `true`, будет выдана ошибка уровня `E_WARNING` в случае неудачной проверки утверждения. Эта INI-настройка неэффективна, если включена assert.exception.

Опции, начинающиеся с assert., могут быть настроены с помощью функции assert_options(). Однако это не рекомендуется.

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

assertion

Любое выражение, возвращающее значение, которое будет выполнено, а результат используется для указания того, удалась или не удалась проверка утверждения.

Внимание

До версии PHP 8.0.0, если параметр assertion представлял собой строку (string), он интерпретировался как PHP-код и выполнялся с помощью функции eval(). Эта строка передавалась в callback-функцию в качестве третьего аргумента. Это поведение УСТАРЕЛО в PHP 7.2.0 и УДАЛЕНО в PHP 8.0.0.

description

Если параметр description является экземпляром класса Throwable, он будет выброшен только в том случае, если проверка утверждения assertion не удастся.

Замечание:
Начиная с PHP 8.0.0, это делается до вызова потенциально определённой callback-функции утверждения.

Замечание:
Начиная с PHP 8.0.0, объект (object) будет выброшен независимо от конфигурации параметра assert.exception.

Замечание:
Начиная с PHP 8.0.0, параметр assert.bail не имеет никакого эффекта в этом случае.

Если параметр description является строкой (string), это сообщение будет использоваться в случае выбрасывания исключения или предупреждения. Необязательное описание, которое будет включено в сообщение, если проверка утверждения assertion не удастся.

Если параметр description опущен. Во время компиляции создаётся описание по умолчанию, равное исходному коду для вызова assert().

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

Возвращает false, если проверка провалена, true в противном случае.

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

Версия	Описание
8.0.0	assert() больше не будет оценивать строковые аргументы, вместо этого они будут рассматриваться как любой другой аргумент. Вместо `assert($a == $b)` следует использовать `assert('$a == $b')`. Директива `assert.quiet_eval` `php.ini` и константа `ASSERT_QUIET_EVAL` также были удалены, поскольку они больше не будут иметь никакого эффекта.
8.0.0	Если параметр `description` является экземпляром класса Throwable, объект выбрасывается в случае неудачной проверки утверждения, независимо от значения assert.exception.
8.0.0	Если параметр `description` является экземпляром класса Throwable, пользовательская callback-функция не вызывается, даже если она установлена.
8.0.0	Объявление функции с именем `assert()` внутри пространства имён больше не допускается и выдаёт ошибку уровня `E_COMPILE_ERROR`.
7.3.0	Объявление функции `assert()` внутри пространства имён устарело. Такое объявление теперь выдаёт ошибку уровня `E_DEPRECATED`.
7.2.0	Использование строки (string) в качестве `assertion` устарело. Теперь оно выдаёт ошибку уровня `E_DEPRECATED`, когда значение и assert.active и zend.assertions равно `1`.

Примеры

Ожидания

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

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

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

Оцениваемые утверждения кода (только для PHP 7)

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

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

<?php
// Активируйте утверждение и отключите error_reporting
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');

// Создайте утверждение, которое должно потерпеть неудачу
$array = [];
assert('count($array);');
?>

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

Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 21
<hr>Утверждение не выполнено:
        Файл 'test.php'<br />
        Строка '21'<br />
        Код 'count($array);'<br /><hr />

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

<hr>Утверждение не выполнено:
        Файл 'test.php'<br />
        Строка '21'<br />
        Код 'count($array);'<br /><hr />

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

<?php
// Активируйте утверждение и отключите error_reporting
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', 'Два меньше, чем один');
?>

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

Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 21
Утверждение не выполнено в test.php:21: 2 < 1

Deprecated: assert(): Calling assert() with a string argument is deprecated in test.php on line 22
Утверждение не выполнено в test.php:22: 2 < 1: Два меньше, чем один

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

Утверждение не выполнено в test.php:21: 2 < 1
Утверждение не выполнено в test.php:22: 2 < 1: Два меньше, чем один

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

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