(PHP 4, PHP 5, PHP 7, PHP 8)
assert — Executa uma asserção
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 podem ser utilizadas para ajudar em depuração.
Um dos usos é para funcionar como verificações de sanidade para precondições
que precisam ser sempre true e caso elas não sejam confirmadas, 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. Sua assinatura deve ser: |
Anteriormente ao PHP 8.0.0, a assinatura deveria ser: Descontinuado a partir do 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. |
assertionPode 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
de 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=0zend.assertions=-1assert.active=0assert.exception=1assert.bail=1description.
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 as asserções estiverem ativadas (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 as asserções estiverem desativadas (zend.assertions=0 ou zend.assertions=-1),
o exemplo acima emitirá:
Hi!
Exemplo #2 Utilizando uma mensagem customizada
<?php
assert(1 > 2, "Esperado que um seja maior que dois");
echo 'Hi!';Se as asserções estiverem ativadas, o código acima emitirá:
Fatal error: Uncaught AssertionError: Esperado que um seja maior que dois in example.php:2
Stack trace:
#0 example.php(2): assert(false, 'Esperado que um...')
#1 {main}
thrown in example.php on line 2
Se as asserções estiverem desativadas, o código acima emitirá:
Hi!
Exemplo #3 Utilizando uma classe de exceção
<?php
class ArithmeticAssertionError extends AssertionError {}
assert(1 > 2, new ArithmeticAssertionError("Esperado que um seja maior que dois"));
echo 'Hi!';Se as asserções estiverem ativas, o exemplo acima emitirá:
Fatal error: Uncaught ArithmeticAssertionError: Esperado que um seja maior que dois in example.php:4
Stack trace:
#0 {main}
thrown in example.php on line 4
Se as asserções estiverem desativadas o exemplo acima emitirá:
Hi!