Function Assert

Descrição

PHP 5

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

PHP 7

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

assert() verifica a assertion informada e toma a ação apropriada se seu resultado é FALSE.

Asserts tradicionais (PHP 5 and 7)

Se o parâmetro assertion é dado como uma string ela será avaliada como código PHP pela função assert(). As vantagens de uma assertion string são menor sobrecarga na conferência se a afirmação é verdadeira e mensagens contendo assertion quando a afirmação é falsa. Isto indica que se você passar uma condição booleana (verdadeiro ou falso) como assertion esta condição não será mostrada como parâmetro da função de assert, o qual você deve ter definido com a função assert_options(), a condição é convertida para uma string antes que a função gerenciadora seja chamada e o booleano FALSE é convertido para uma string vazia.

Asserts devem ser usadas apenas com a intenção de eliminar erros apenas. Você deve usa-las para testar condições que devam ser sempre TRUE e que indiquem algum erro de programação ou para verificar a existência/disponibilidade de funções, extensões ou ainda de limites e recursos do sistema.

Asserts não devem ser usadas para operações em tempo de execução normais como para conferir certo valor de entrada. Como uma dica de uso, o seu código deve funcionar corretamente mesmo que os asserts não estejam ativados.

O funcionamento de assert() pode ser configurado por assert_options() ou pelas configurações descritas na pagina do manual para estas funções.

A função assert_options() e/ou a diretiva de configuração ASSERT_CALLBACK permitem configurar uma função para ser chamada no caso de falha da afirmação.

assert() callbacjs são particularmente úteis quando estiver criando sistemas automáticos para testes porque permitem que você capture facilmente o código passado para a afirmação em conjunto com informações sobre onde a afirmação foi feita. Enquanto esta informação pode ser capturada por outros métodos, usar afirmações torna muito mais fácil e rápido!

A função de callback deve aceitar três argumentos. O primeiro irá conter o arquivo onde houve a falha na afirmação. O segundo argumento irá conter a linha onde a afirmação falhou e o terceiro argumento irá conter a expressão que falhou (se houver alguma — valores literais como 1 or "dois" não serão passados nesse argumento). Usuários do PHP 5.4.8 e posteriores também devem providenciar um quarto argumento opcional, que conterá o description informado no assert() it was set.

Expectations (PHP 7 only)

assert() é um constructo de linguagem no PHP 7, permitindo a definição de expectativas: asserts que tem efeitos em ambientes de desenvolvimento e testes, mas que são removidos com custo zero em produção.

Ainda que assert_options() possa ser utilizado para controlar comportamentos descritos acima por razões de compatibilidade reversa, o PHP 7 somente deve usar duas novas diretivas para controlar o comportamento de assert() e evitar chamar assert_options().

**Diretivas de configuração para **assert()** no PHP 7**
Diretiva	Padrão	Valores possíveis
zend.assertions	1	1: gera e executa código (modo de desenvolvimento) 0: gera código, mas não o executa -1: não gera código (modo de produção)
assert.exception	0	1: interrompe se o assert falhar, ou lançando a exceção fornecida no parâmetro `exception` ou lançando um objeto AssertionError se `exception` não tiver sido informado 0: usa e gera um Throwable como descrito acima, mas somente gera um warning em baseado no objeto em vez de lançar a exceção (comportamento compatível com o PHP 5)

Parâmetros

assertion: A asserção. No PHP 5 isto precisa ser uma string a ser executada ou um boolean para ser testado. No PHP 7 pode ser também uma expressão que retorna valores, qual será executada e o resultado será usado para indicar se a asserção confirmou-se ou falhou.
description: Uma descrição opctional que será incluída na mensagem de falha de caso de assertion falhar.
exception: No PHP 7 o segundo parâmetro pode ser um objeto Throwable em vez de uma string string, e nesse caso o objeto será lançado caso o assert falhe e assert.exception estiver habilitado.

Valor Retornado

FALSE se o assert é falso, TRUE nos demais casos.

Changelog

Versão	Descrição
7.0.0	assert() agora é um constructo de linguagem e não mais uma função. assertion() agora pode ser uma expressão. O segundo parâmtro pode ser interpretado como um `exception` (se do tipo Throwable) ou como uma string, funcionando como o campo `description` do PHP 5.4.8 e posteriores.
5.4.8	O parâmetro `description` foi adicionado. O parâmetro `description` é informado na função callback no modo `ASSERT_CALLBACK` como o quarto argumento.

Exemplos

Asserts tradicionais (PHP 5 e 7)

Exemplo #1 Lida com um assert falho com um manipulador próprio


<?php
// Ativa asserts configura silêncio
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Cria a função de manipulação
function my_assert_handler($file, $line, $code)
{
    echo "<hr>Assertion Failed:
        File '$file'<br />
        Line '$line'<br />
        Code '$code'<br /><hr />";
}

// Configura o callback
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Realiza um assert que deve falhar
assert('mysql_query("")');
?>

Exemplo #2 Utilizando um manipulador para imprimir uma descrição


<?php
// Ativa asserts configura silêncio
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Cria a função de manipulação
function my_assert_handler($file, $line, $code, $desc = null)
{
    echo "Assertion failed at $file:$line: $code";
    if ($desc) {
        echo ": $desc";
    }
    echo "\n";
}

// Configura o callback
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Make an assertion that should fail
assert('2 < 1');
assert('2 < 1', 'Two is less than one');
?>

O exemplo acima irá imprimir:

Assertion failed at test.php:21: 2 < 1
Assertion failed at test.php:22: 2 < 1: Two is less than one

Expectativas (PHP 7 somente)

Exemplo #3 Expectativs sem uma exceção configurada


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

Com zend.assertions configurado para 0 o exemplo acima imprimirá:

Hi!

Com zend.assertions configurado para 1 e assert.exception para 0 O exemplo acima imprimirá:

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

Com zend.assertions configurado para 1 e assert.exception para 1 o exemplo acima imprimirá:

Fatal error: Uncaught AssertionError: assert(true == false) in -:2
Stack trace:
#0 -(2): assert(false, 'assert(true == ...')
#1 {main}
 thrown in - on line 2

Exemplo #4 Expectativs com uma exceção configurada


<?php
class CustomError extends AssertionError {}

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

Com zend.assertions configurado para 0 o exemplo acima imprirá:

Hi!

Com zend.assertions configurado para 0 e assert.exception para 0 o exemplo acima imprimirá:

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