assert
(PHP 4, PHP 5, PHP 7, PHP 8)
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-функцию определяют со следующей сигнатурой:
|
До PHP 8.0.0 сигнатуру callback-функции определяли так:
Директива устарела с 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=0zend.assertions=-1assert.active=0assert.exception=1assert.bail=1- В параметр
description передали объект пользовательского исключения.
Функция assert() проверяет утверждения
и возвращает true при истинности аргумента assertion,
но только если ни одно из отключающих проверки условий не выполняется,
иначе функция возвращает false.
Примеры
Пример #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
Приведённый пример выведет следующее, если утверждения выключили:
