(PHP 4, PHP 5, PHP 7, PHP 8)
assert — Executa um assert
assert() permite a definição de expectativas: asserções são verificadas em ambientes de desenvolvimento ou testes, mas que são removidas por otimização a custo zero em produção.
Asserções devem ser utilizadas como uma ferramenta apenas de debug. Um dos usos é para funcionar como validações graves, para precondições que precisam ser true
e caso isso não ocorra, isto indica algum erro de programação. Outro uso é garantir a presença de certos recursos, como por exemplo funções de extensões ou certos recursos ou limites de sistema.
As asserções podem ser configurados para serem eliminados, e elas não não devem ser utilizados em operações comuns como por exemplo a validação de parâmetros. Como regra geral, o código deve se comportar igual mesmo no caso das asserções estarem desativadas.
assert() verificará se a expectativa informada no parâmetro assertion
é válida. Se não, o resultado avaliado é false
, ocorrerá a ação apropriada, dependendo em como assert() está configurado.
O comportamento de assert() é ditado pelas seguintes configurações INI:
Nome | Padrão | Descrição | Registro de Alterações |
---|---|---|---|
zend.assertions | 1 |
| |
assert.active | true | Se false , assert() não verifica a expectativa e retorna true imediatamente. | Descontinuado desde o PHP 8.3.0. |
assert.callback | null | Uma função definida pelo usuário a ser chamada quando a asserção falha. A assinatura deve ser: | Anteriormente ao PHP 8.0.0, a assinatura deveria ser: Descontinuado desde o PHP 8.3.0. |
assert.exception | true | Se true irá lançar um AssertionError no caso da expectativa não ser válida. | Descontinuado desde o PHP 8.3.0. |
assert.bail | false | Se true então a execução do script PHP será abortada caso a expectativa não seja válida. | Descontinuado desde o PHP 8.3.0. |
assert.warning | true | Se true , será emitido um E_WARNING no caso da expectativa não seja válida. Essa configuração INI é inefetiva caso assert.exception esteja ativo. | Descontinuado desde o PHP 8.3.0. |
assertion
Pode ser qualquer expressão que retorna um valor, qual será executado e o resultado é utilizado para indicar se a asserção deve passar ou falhar.
description
Se description
é uma instância de Throwable, ela será lançada somente se assertion
for executada e falhar.
Nota:
A partir do 8.0.0, isto ocorria antes de chamar a função de callback potencialmente definida.
Nota:
A partir do PHP 8.0.0, o object será lançado independente da configuração de assert.exception.
Nota:
A partird do PHP 8.0.0, a configuração assert.bail não terá efeito nesse caso.
Se description
é uma string esta mensagem será utilizada em uma exceção ou em um aviso. Uma descrição opcional que será incluída na mensagem de falha no caso da assertion
falhar.
Se description
é omitido. Uma descrição padrão, igual ao código fonte na invocação de assert() é criada em tempo de compilação.
assert() sempre retorna true
se ao menos uma das seguintes condições forem verdadeiras:
zend.assertions=0
zend.assertions=-1
assert.exception=1
assert.bail=1
description
. Se nenhuma das condições forem verdadeiras assert() ainda pode retornar true
se assertion
possa ser convertido em um valor verdadeiro, ou false
nos demais casos.
Versão | Descrição |
---|---|
8.3.0 | Todas as configurações INI assert. estão desencorajadas. |
8.0.0 | assert() não mais avaliará argumentos strings, e por outro lado elas serão tratadas como um argumento comum. assert($a == $b) deve ser utilizado ao invés de assert('$a == $b') . A diretiva assert.quiet_eval php.ini e a constante ASSERT_QUIET_EVAL também foram removidos, dado que elas não tem mais nenhum efeito. |
8.0.0 | Se description é uma instância de Throwable, a exceção é lançada no caso da asserção falhar, independentemente do valor de assert.exception. |
8.0.0 | Se description é uma instância de Throwable, o callback não é chamado, mesmo que ele seja informado. |
8.0.0 | Declarar uma função chamada assert() dentro de um namespace não é mais permitido, e emite um E_COMPILE_ERROR . |
7.3.0 | Declarar uma função chamada assert() dentro de um namespace foi descontinuado. Uma declaração assim emite um E_DEPRECATED . |
7.2.0 | Uso de strings no argumento assertion foi descontinuado. Isto agora emite um aviso E_DEPRECATED quando ambos assert.active e zend.assertions estão configurados para 1 . |
Exemplo #1 Exemplo de assert()
<?php
assert(1 > 2);
echo 'Hi!';
Se assertions estiver ativo (zend.assertions=1
), o exemplo acima emitirá:
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
Se assertions estiver desativado (zend.assertions=0
ou zend.assertions=-1
) o exemplo acima emitirá:
Hi!
Exemplo #2 Utilizando uma mensagem customizada
<?php
assert(1 > 2, "Expected one to be greater than two");
echo 'Hi!';
Se assertions estiverem ativadas, o código acima emitirá:
Fatal error: Uncaught AssertionError: Expected one to be greater than two in example.php:2 Stack trace: #0 example.php(2): assert(false, 'Expected one to...') #1 {main} thrown in example.php on line 2
Se assertions estiverem desativados, o código acima emitirá:
Hi!
Exemplo #3 Utilizando uma classe exception
<?php
class ArithmeticAssertionError extends AssertionError {}
assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
echo 'Hi!';
Se assertions estiver ativo o exemplo acima emitirá:
Fatal error: Uncaught ArithmeticAssertionError: Expected one to be greater than two in example.php:4 Stack trace: #0 {main} thrown in example.php on line 4
Se assertions estiver desativado, o exemplo acima emitirá:
Hi!