phpday 2025 - Call For Papers

assert

(PHP 4, PHP 5, PHP 7, PHP 8)

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

Описание

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, безоговорочно. Директива устарела начиная с PHP 8.3.0.
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

Директива устарела начиная с 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, если утверждение 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().

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

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

  • zend.assertions=0
  • zend.assertions=-1
  • 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 Строка (string) как assertion устарела. Теперь выдаётся ошибка уровня 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 or 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() - Устанавливает или получает флаги проверки утверждения

Добавить

Примечания пользователей 2 notes

up
33
hodgman at ali dot com dot au
16 years ago
As noted on Wikipedia - "assertions are primarily a development tool, they are often disabled when a program is released to the public." and "Assertions should be used to document logically impossible situations and discover programming errors— if the 'impossible' occurs, then something fundamental is clearly wrong. This is distinct from error handling: most error conditions are possible, although some may be extremely unlikely to occur in practice. Using assertions as a general-purpose error handling mechanism is usually unwise: assertions do not allow for graceful recovery from errors, and an assertion failure will often halt the program's execution abruptly. Assertions also do not display a user-friendly error message."

This means that the advice given by "gk at proliberty dot com" to force assertions to be enabled, even when they have been disabled manually, goes against best practices of only using them as a development tool.
up
9
sven at rtbg dot de
9 months ago
With the current changes made in PHP 8.3 (deprecating the INI settings affecting assertions) and the increasing amount of open source libraries utilizing `assert()` as an easy means to ensure obscure return cases of PHP core function calls are in fact not triggered (e.g. no NULL or FALSE has been returned, but the useful value), the comment made about assertions only being a tool used during development should be considered invalid.

In addition, static code analysis tools use the knowledge gained from `assert($x instanceof MyClass)` to know the type or types that are possible.

Assertions are actively being used in production code, they are useful, and disabling them would only gain minimal performance benefits because the asserted expression usually is very small.

Use this tool where applicable!
To Top