assert

(PHP 4, PHP 5)

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

Описание

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

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

Если 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().

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

assertion

Утверждение.

description

Дополнительное описание, которое будет включено в сообщение об ошибке, если проверка assertion завершится неудачей.

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

FALSE в случае провала проверки, TRUE в остальных случаях.

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

Версия Описание
5.4.8 Добавлен аргумент description. Также description передается четвертым аргументом в callback-функцию в режиме ASSERT_CALLBACK.

Примеры

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

<?php
// Активируем проверку утверждений и сделаем его фоновым
assert_options(ASSERT_ACTIVE1);
assert_options(ASSERT_WARNING0);
assert_options(ASSERT_QUIET_EVAL1);

// Создадим функцию обработчик
function my_assert_handler($file$line$code)
{
    echo 
"<hr>Проверка утвеждения провалена:
        Файл '
$file'<br />
        Строка '
$line'<br />
        Код '
$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 
"Проверка завершилась неудачей в $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: Два меньше одного

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

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

Коментарии

Here is a simple demonstration of Design By Contract with PHP

<?php

assert_options
(ASSERT_ACTIVE1);
assert_options(ASSERT_WARNING0);
assert_options(ASSERT_BAIL1);
assert_options(ASSERT_CALLBACK'dcb_callback');

function 
dcb_callback($script$line$message) {
    echo 
"<h1>Condition failed!</h1><br />
        Script: <strong>$script</strong><br />
        Line: <strong>$line</strong><br />
        Condition: <br /><pre>$message</pre>"
;
}

// Parameters
$a 5;
$b 'Simple DCB with PHP';

// Pre-Condition
assert('
    is_integer($a) &&
    ($a > 0) &&
    ($a < 20) &&
   
    is_string($b) &&
    (strlen($b) > 5);
'
);

// Function
function combine($a$b) {
    return 
"Kombined: " $b $a;
}

$result combine($a$b);

// Post-Condition
assert('
    is_string($result) &&
    (strlen($result) > 0);
'
);

// All right, the Function works fine
var_dump($result);

?>
2006-09-13 13:51:05
http://php5.kiev.ua/manual/ru/function.assert.html
Note that func_get_args() should be used carefully and never in a string! For example:

<?php
function asserted_normal($a$b) {
   
assert(var_dump(func_get_args()));
    }
function 
asserted_string($a$b) {
   
assert('var_dump(func_get_args())');
    }
?>

<?php asserted_normal(1,2?> prints
array(2) {
  [0]=>
  int(1)
  [1]=>
  int(2)
}

but <?php asserted_string(3,4?> prints
array(1) {
  [0]=>
  string(25) "var_dump(func_get_args())"
}

This is because of that the string passed to assert() is being evaled inside assert, and not your function. Also, note that this works correctly, because of the eval scope:

<?php
function asserted_evaled_string($a$b) {
   
assert(eval('var_dump(func_get_args())'));
    }
asserted_evaled_string(5,6);
?>
array(2) {
  [0]=>
  int(5)
  [1]=>
  int(6)
}

(oh, and for simplicity's sake the evaled code doesn't return true, so  don't worry that it fails assertion...)
2007-10-01 21:13:06
http://php5.kiev.ua/manual/ru/function.assert.html
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.
2008-07-29 00:19:43
http://php5.kiev.ua/manual/ru/function.assert.html
There's a nice advantage to giving assert() some code to execute, as a string, rather than a simple true/false value: commenting.

<?php

assert
('is_int($int) /* $int parameter must be an int, not just numeric */');

// and my personal favorite
assert('false /* not yet implemented */');

?>

The comment will show up in the output (or in your assertion handler) and doesn't require someone debugging to go through your code trying to figure out why the assertion happened. That's no excuse to not comment your code, of course.

You need to use a block comment (/*...*/) because a line comment (//...) creates an "unexpected $end" parse error in the evaluated code. Bug? Could be.
(You can get around it with "false // not yet implemented\n" but that screws up the message)
2010-06-20 16:48:22
http://php5.kiev.ua/manual/ru/function.assert.html
Example from Ikac Framework how they use assert()

<?php

   
/**
     * Set Assertion Debug
     * 
     * This method will check the given assertion and take appropriate -
     * action if its result is FALSE. 
     * 
     * This file is part of Ikac Framework.
     * 
     * @package Ikac Framework
     * @author Ivan Stojmenovic Ikac <contact.@stojmenovic.info>
     * 
     * @param mixed $assertion  The assertion.
     * @param mixed $callback Callback to call on failed assertions
     * @param array $options  Set the various control options or just query their current settings. 
     * @param string $description  An optional description that will be included in the failure message if the assertion fails. 
     */
   
public function setAssertionDebug($assertion$callback, array $options$description null)
    {
        if (
is_array($options)) {
            foreach (
$options AS $option => $value) {
               
assert_options($option$value);
            }
        }
        if (
$callback) {
           
assert_options(ASSERT_CALLBACK$callback);
        }
       
        return 
assert($assertion$description);
    }
   
?>

How to use:

<?php
     
use IkacComponentSystemBehaviourOptionsInfo;

     
$system = new OptionsInfo();

     
$option = array(ASSERT_ACTIVE => 1,ASSERT_WARNING => 0,ASSERT_QUIET_EVAL => 1);

     
$system->setAssertionDebug('2<1', function(){
            echo 
"Assertion failed";
     }, 
$option);

?>
2013-09-20 03:35:35
http://php5.kiev.ua/manual/ru/function.assert.html
Автор:
if there was no 'warning' message when assertion failed (FALSE), try reset the error handler:
<?php
set_error_handler 
null );
2016-08-26 12:51:57
http://php5.kiev.ua/manual/ru/function.assert.html

    Поддержать сайт на родительском проекте КГБ