assert

(PHP 4, PHP 5, PHP 7)

assertПроверка утверждения (равен ли результат FALSE)

Описание

PHP 5

bool assert ( mixed $assertion [, string $description ] )

PHP 7

bool assert ( mixed $assertion [, Throwable $exception ] )

assert() проверит заданное утверждение assertion и совершит соответствующее действие, если результатом проверки окажется FALSE.

Традиционная работа функции assert (PHP 5 и 7)

Если assertion задается в виде строки, оно будет рассматриваться функцией assert() как PHP код. Представление assertion в виде строки имеет свои преимущества. Во-первых, выключение проверки утверждений снижает накладные расходы. Во-вторых, сообщения о провале проверки будут содержать само утверждение assertion. То есть, если передать в качестве assertion какое-либо условное выражение, это условие невозможно будет получить в явном виде, в котором оно передавалось в проверяющую функцию, которую вы возможно определили с помощью assert_options(). Это условное выражение будет вычислено и преобразовано в строку до вызова проверяющей функции, соответственно логическое FALSE будет фигурировать в сообщении как пустая строка.

Утверждения должны использоваться только в целях отладки. Их можно использовать для тестирования каких-то условий, которые в штатных ситуациях всегда принимают значение TRUE, обратное должно указывать на программные ошибки. Также их можно использовать, чтобы удостовериться в наличии каких-либо расширений или системных ограничений.

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

Поведение функции assert() можно изменять с помощью функции assert_options() или заданием .ini-настроек.

Функция assert_options() и директива ASSERT_CALLBACK позволяют задать callback-функцию, которая будет вызываться при провале проверки утверждения.

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

Callback-функция должна принимать три аргумента. Первый аргумент должен содержать файл, в котором утверждение не прошло проверку. Второй аргумент отвечает за номер строки в этом файле. В третьем аргументе будет передаваться выражение, содержащее ошибку (если таких несколько, строковые значение, вроде 1 или "два" не будут передаваться через этот аргумент). Пользователи PHP версий 5.4.8 и выше могут задать четвертый необязательный аргумент description, который будет также передан в функцию assert().

Ожидания (только PHP 7)

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

В то время как функция assert_options() может по прежнему быть использована для контроля над поведением программы описанным выше образом, для обратной совместимости, но в PHP 7 код должен использовать две новые конфигурационные директивы для управления поведением assert() и не вызывать функцию assert_options().

Конфигурационные директивы PHP 7 для функции assert() Директива Значение по умолчанию Возможные значения
zend.assertions 1
  • 1: генерирует и выполняет код (режим разработки)
  • 0: генерирует код, но перепрыгивает через него во время выполнения
  • -1: не генерирует код (продуктивный режим)
assert.exception 0
  • 1: выбрасывает исключение когда утверждение ложно выбрасывает объект, переданный в параметре exception, либо выбрасывает экземпляр нового класса AssertionError, если параметр exception не передан.
  • 0: использует или создает экземпляр класса Throwable как сказано выше, но только генерирует предупреждение на основе этого объекта, но не выбрасывает его (для совместимости с поведением PHP 5)

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

assertion

Утверждения. В PHP 5, они могут быть либо string чтобы быть выполнены или boolean для проверки. В PHP 7, это могут быть также любые выражения, возвращающие значение, которые могут быть выполнены и их результат использован для определения успешности проверки.

Описание

Описание- необязательный параметр, который будет добавлен в сообщение, если проверка утверждения assertion будет провалена.

Исключение

В PHP 7, второй параметр может быть объектом Throwable, вместо string. Этот объект будет выброшен в случае провала проверки утверждения при включенной конфигурационной директиве assert.exception.

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

FALSE если проверка провалена, и TRUE в противном случае.

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

Версия Описание
7.0.0 assert() теперь языковая конструкция, а не функция. assertion() теперь может быть выражением. Второй параметр теперь интерпретируется как исключение exception (если передан объект Throwable), или как описание description, поддерживаемое с версии PHP 5.4.8 и далее.
5.4.8 Добавлен параметр description. Параметр description также поддерживает callback функции в режиме ASSERT_CALLBACK, который может быть установлен четвертым аргументом argument.

Примеры

Традиционная работа функции assert (PHP 5 и 7)

Пример #1 Обработка неудачных проверок утверждений с использованием собственного обработчика

<?php
// Активация утверждений и покашение вывода оибок
assert_options(ASSERT_ACTIVE1);
assert_options(ASSERT_WARNING0);
assert_options(ASSERT_QUIET_EVAL1);

// Создание обработчика
function my_assert_handler($file$line$code)
{
    echo 
"<hr>Assertion Failed:
        File '
$file'<br />
        Line '
$line'<br />
        Code '
$code'<br /><hr />";
}

// Подключение callback функции
assert_options(ASSERT_CALLBACK'my_assert_handler');

// Выполнение проверки утверждения, которое завершится неудачей
assert('mysql_query("")');
?>

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

<?php
// Активация утверждений и покашение вывода оибок
assert_options(ASSERT_ACTIVE1);
assert_options(ASSERT_WARNING0);
assert_options(ASSERT_QUIET_EVAL1);

// Создание обработчика
function my_assert_handler($file$line$code$desc null)
{
    echo 
"Assertion failed at $file:$line$code";
    if (
$desc) {
        echo 
": $desc";
    }
    echo 
"n";
}

// Подключение callback функции
assert_options(ASSERT_CALLBACK'my_assert_handler');

// Выполнение проверки утверждения, которое завершится неудачей
assert('2 < 1');
assert('2 < 1''Два больше чем один');
?>

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

 Assertion failed at test.php:21: 2 < 1
 Assertion failed at test.php:22: 2 < 1: Два больше чем один
 

Ожидания (только PHP 7)

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

<?php
assert
(true == false);
echo 
'Hi!';
?>

При директиве zend.assertions установленной в 0, данный код выведет:

Hi!

При директивах zend.assertions установленной в 1 и assert.exception установленной в 0, данный пример выведет:

Warning: assert(): assert(true == false) failed in - on line 2
Hi!

При директивах 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

Пример #4 Ожидания собственным исключением

<?php
class CustomError extends AssertionError {}

assert(true == false, new CustomError('True is not false!'));
echo 
'Hi!';
?>

При директиве zend.assertions установленной в 0, данный код выведет:

Hi!

При директивах zend.assertions установленной в 1 и assert.exception установленной в 0, данный код выведет:

Warning: assert(): CustomError: True is not false! in -:4
Stack trace:
#0 {main} failed in - on line 4
Hi!

При директивах zend.assertions установленной в 1 и assert.exception установленной в 1, даный код выведет:

Fatal error: Uncaught CustomError: True is not false! in -:4
Stack trace:
#0 {main}
  thrown in - on line 4

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

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