Описание

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

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

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

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

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

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

Имя По умолчанию Описание Список изменений

zend.assertions 1

1: генерирует и выполняет код. Значение указывают в режиме разработки

0: генерирует, но не выполняет код при выполнении

-1: не генерирует код. Значение указывают в производственном режиме

assert.active true Со значением false функция assert() не проверяет ожидание и возвращает true без проверки утверждения. Директива устарела с PHP 8.3.0.

assert.callback null
Пользовательская функция, которая вызывается, если утверждение не прошло проверку. Callback-функцию определяют со следующей сигнатурой:
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

Директива устарела с PHP 8.3.0.

assert.exception true Со значением true функция выбрасывает исключение AssertionError, если ожидание не оправдалось. Директива устарела с PHP 8.3.0.

assert.bail false Со значением true выполнение PHP-скрипта прервётся, если ожидание не оправдалось. Директива устарела с PHP 8.3.0.

assert.warning true Со значением true функция выдаёт ошибку уровня E_WARNING, если ожидание не оправдалось. INI-настройка не работает, если включили директиву assert.exception. Директива устарела с PHP 8.3.0.

**Опции настройки конструкции assert**
Имя	По умолчанию	Описание	Список изменений
zend.assertions	`1`	`1`: генерирует и выполняет код. Значение указывают в режиме разработки `0`: генерирует, но не выполняет код при выполнении `-1`: не генерирует код. Значение указывают в производственном режиме
assert.active	`true`	Со значением `false` функция assert() не проверяет ожидание и возвращает `true` без проверки утверждения.	Директива устарела с PHP 8.3.0.
assert.callback	`null`	Пользовательская функция, которая вызывается, если утверждение не прошло проверку. Callback-функцию определяют со следующей сигнатурой: 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 Директива устарела с PHP 8.3.0.
assert.exception	`true`	Со значением `true` функция выбрасывает исключение AssertionError, если ожидание не оправдалось.	Директива устарела с PHP 8.3.0.
assert.bail	`false`	Со значением `true` выполнение PHP-скрипта прервётся, если ожидание не оправдалось.	Директива устарела с PHP 8.3.0.
assert.warning	`true`	Со значением `true` функция выдаёт ошибку уровня `E_WARNING`, если ожидание не оправдалось. INI-настройка не работает, если включили директиву assert.exception.	Директива устарела с PHP 8.3.0.

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

assertion

Выражение, значение возврата которого выполняется, а резлультат выполнения указывает, прошло ли утверждение проверку.

Внимание

До PHP 8.0.0 аргумент с типом string для параметра assertion интерпретировался как 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 PHP на этапе компиляции сгенерирует описание ошибки, эквивалентное строке исходного кода самого утверждения assert().

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

Функция assert() возвращает значение true, если хотя бы одно из следующих утверждений истинно:

zend.assertions=0
zend.assertions=-1
assert.active=0
assert.exception=1
assert.bail=1
В параметр description передали объект пользовательского исключения.

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

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

Версия Описание

8.3.0 INI-настройки assert. устарели.

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 Передача в параметр assertion утверждений в значении с типом string устарела. Функция теперь выдаст ошибку уровня E_DEPRECATED, когда и для опции assert.active, и для опции zend.assertions установили значение 1.

Версия	Описание
8.3.0	INI-настройки `assert.` устарели.
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	Передача в параметр `assertion` утверждений в значении с типом string устарела. Функция теперь выдаст ошибку уровня `E_DEPRECATED`, когда и для опции assert.active, и для опции zend.assertions установили значение `1`.

Примеры

Пример #1 Пример проверки утверждения функцией assert()

<?php

assert(1 > 2);
echo 'Привет!';

?>

Приведённый пример выведет следующее, если утверждения включили в директиве zend.assertions=1:

Fatal error: Uncaught AssertionError: assert(1 > 2) in example.php:2
Stack trace:
#0 example.php(2): assert(false, 'assert(1 > 2)')
#1 {main}
  thrown in example.php on line 2

Приведённый пример выведет следующее, если утверждения отключили путём установки для директивы значений zend.assertions=0 или zend.assertions=-1:

Привет!

Пример #2 Пример пользовательского сообщения

<?php

assert(1 > 2, "Ожидается, что один больше двух");
echo 'Привет!';

?>

Приведённый пример выведет следующее, если утверждения включили:

Fatal error: Uncaught AssertionError: Ожидается, что один больше двух in example.php:2
Stack trace:
#0 example.php(2): assert(false, 'Expected one to...')
#1 {main}
  thrown in example.php on line 2

Приведённый пример выведет следующее, если утверждения выключили:

Привет!

Пример #3 Пример пользовательского класса ошибок

<?php

class ArithmeticAssertionError extends AssertionError {}

assert(1 > 2, new ArithmeticAssertionError("Ожидается, что один больше двух"));
echo 'Hi!';

?>

Приведённый пример выведет следующее, если утверждения включили:

Fatal error: Uncaught ArithmeticAssertionError: Ожидается, что один больше двух in example.php:4
Stack trace:
#0 {main}
  thrown in example.php on line 4

Приведённый пример выведет следующее, если утверждения выключили:

Привет!

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

assert_options() - Устанавливает или получает флаги проверки утверждения