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.assertions1
    • 1: генерирует и выполняет код (режим разработки)
    • 0: генерирует код, но перепрыгивает через него во время выполнения
    • -1: не генерирует код (рабочий режим)
    		 
    assert.activetrue Если false, функция assert() не проверяет ожидание и возвращает true, безоговорочно. Устарела с PHP 8.3.0.
    assert.callbacknull Определяемая пользователем функция, вызываемая в случае неудачной проверки утверждения. Её сигнатура должна быть следующей:
    assert_callback(
        string$file,
        int$line,
        null$assertion,
        string$description = ?
    ): void
    Устарела с PHP 8.3.0.     		До PHP 8.0.0 сигнатура callback-функции должна быть:
    assert_callback(
        string$file,
        int$line,
        string$assertion,
        string$description = ?
    ): void
    assert.exceptiontrue Если true, будет выброшена ошибка AssertionError в случае неудачной проверки утверждения. Устарела с PHP 8.3.0.
    assert.bailfalse Если true, выполнение PHP-скрипта прервётся в случае неудачной проверки утверждении. Устарела с PHP 8.3.0.
    assert.warningtrue Если 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_evalphp.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() - Установка и получение настроек механизма проверки утверждений
    To Top