assert
(PHP 4, PHP 5, PHP 7, PHP 8)
assert — Executa um assert
Descriçã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:
Assert Opções de Configuração
Nome |
Padrão |
Descrição |
Registro de Alterações |
zend.assertions |
1 |
-
1 : gera e executa o código (modo de desenvolvimento)
-
0 : gera o código mas ignora durante a execução
-
-1 : não gera o código (modo de produção)
|
|
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 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.
|
Parâmetros
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.
Aviso
Anteriormente ao PHP 8.0.0, se assertion
era uma
string ela era interpretada como código PHP e executada via
eval().
A string era passada para o argumento do callback no terceiro argumento.
Este comportamento está DESCONTINUADO desde o PHP 7.2.0,
e foi REMOVIDO no PHP 8.0.0.
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.
Valor Retornado
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
- Um objeto exception foi passado em
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.
Exemplos
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á:
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á:
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á: