Vérifie une assertion

Description

assert(mixed $assertion, Throwable|string|null $description = null): bool

assert() n'est pas une fonction mais une construction du langage. Elle permet de définir des attentes : des assertions qui prennent effet dans les environnements de développement et de test, mais qui sont optimisées pour ne pas avoir de coût en production.

Les assertions doivent être utilisées uniquement comme fonctionnalité de débogage. Un cas d'utilisation pour les assertions est de servir de vérifications de cohérence pour des préconditions qui devraient toujours être true, et si elles ne sont pas respectées, cela indique des erreurs de programmation. Un autre cas d'utilisation est de garantir la présence de certaines fonctionnalités telles que des fonctions d'extension ou certaines limites et fonctionnalités du système.

Comme les assertions peuvent être configurées pour être éliminées, elles ne doivent pas être utilisées pour des opérations normales en cours d'exécution, telles que des vérifications des paramètres d'entrée. En règle générale, le code doit se comporter comme prévu même si la vérification des assertions est désactivée.

assert() vérifiera que l'attente donnée dans assertion est satisfaite. Si ce n'est pas le cas et donc que le résultat est false, elle prendra l'action appropriée en fonction de la configuration de assert().

Le comportement de assert() est dicté par les paramètres INI suivants :

**Assert Options de configuration**
Nom	Défaut	Description	Historique
zend.assertions	`1`	`1` : génère et exécute le code (mode développement) `0` : génère le code mais l'évite au moment de l'exécution `-1` : ne génère pas le code (mode production)
assert.active	`true`	Si `false`, assert() ne vérifie pas l'attente et retourne toujours `true`, sans condition.
assert.callback	`null`	Une fonction définie par l'utilisateur à appeler lorsqu'une assertion échoue. Sa signature devrait être : assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void	Antérieur à PHP 8.0.0, la signature de la fonction de rappel devrait être : assert_callback( string `$file`, int `$line`, string `$assertion`, string `$description` = ? ): void
assert.exception	`true`	Si `true`, lancera une AssertionError si l'attente n'est pas respectée.
assert.bail	`false`	Si `true`, interrompra l'exécution du script PHP si l'attente n'est pas respectée.
assert.warning	`true`	Si `true`, émettra un `E_WARNING` si l'attente n'est pas respectée. Ce paramètre INI est inefficace si assert.exception est activé.

Les options commençant par assert. peuvent être configurées via assert_options(). Cependant, cela n'est pas recommandé.

Liste de paramètres

assertion

Ceci est une expression quelconque qui retourne une valeur, qui sera exécutée et dont le résultat sera utilisé pour indiquer si l'assertion a réussi ou échoué.

Avertissement

Antérieur à PHP 8.0.0, si assertion était une string, elle était interprétée comme du code PHP et exécutée via eval(). Cette chaîne était transmise à la fonction de rappel en tant que troisième argument. Ce comportement était OBSOLÈTE dans PHP 7.2.0, et est SUPPRIMÉ à partir de PHP 8.0.0

description

Si description est une instance de Throwable, elle sera lancée uniquement si assertion est exécutée et échoue.

Note:
À partir de PHP 8.0.0, cela est fait avant d'appeler la fonction de rappel d'assertion éventuellement défini

Note:
À partir de PHP 8.0.0, l'objet objet sera lancé indépendamment de la configuration de assert.exception.

Note:
À partir de PHP 8.0.0, le paramètre assert.bail n'a aucun effet dans ce cas.

Si description est une chaîne de caractères, ce message sera utilisé si une exception ou un avertissement est émis. Une description optionnelle, qui sera incluse dans le message d'échec si l'assertion échoue.

Si description est omis. Une description par défaut équivalente au code source de l'appel de assert() est créée au moment de la compilation.

Valeurs de retour

false si l'assertion est fausse, true sinon.

Historique

Version	Description
8.0.0	La fonction assert() n'évaluera plus les arguments de type string, au lieu de cela, ils seront traités comme tout autre argument. `assert($a == $b)` devrait être utilisé à la place du `assert('$a == $b')`. La directive `assert.quiet_eval` `php.ini` et la constante `ASSERT_QUIET_EVAL` ont également été supprimées, car elles n'auraient plus aucun effet.
8.0.0	Si `description` est une instance de Throwable, l'objet est lancé si l'assertion échoue, indépendamment de la valeur de assert.exception.
8.0.0	Si `description` est une instance de Throwable, aucune fonction de rappel utilisateur n'est appelée même si elle est définie.
8.0.0	Déclarer une fonction qui s'appelle `assert()` à l'intérieur d'un espace de nom n'est plus autorisé, et génère une `E_COMPILE_ERROR`.
7.3.0	Déclarer une fonction qui s'appelle `assert()` à l'intérieur d'un espace de nom est devenue obsolète. De telles déclarations génèrent désormais une `E_DEPRECATED`.
7.2.0	L'utilisation d'une chaîne de caractères en tant qu'`assertion` est est devenue obsolète. Ceci émet désormais une notice `E_DEPRECATED` quand assert.active et zend.assertions sont tous les deux définit à `1`.

Exemples

Attentes


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

Avec zend.assertions défini à 0, l'exemple ci-dessus afficherait :

Hi!

Avec zend.assertions défini à 1 et assert.exception défini à 0, l'exemple ci-dessus afficherait :

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

AVec zend.assertions défini à 1 et assert.exception défini à 1, l'exemple ci-dessus afficherait :

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

Exemple #1 Expectations avec une exception personalisée


<?php
class CustomError extends AssertionError {}

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

Avec zend.assertions défini à 0, l'exemple ci-dessus afficherait :

Hi!

Avec zend.assertions défini à 1 et assert.exception défini à 0, l'exemple ci-dessus afficherait :

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

Avec zend.assertions défini à 1 et assert.exception défini à 1, l'exemple ci-dessus afficherait :

Fatal error: Uncaught CustomError: True is not false! in -:4
Stack trace:
#0 {main}
  thrown in - on line 4

Évaluations des assertions de code (uniquement pour PHP 7)

Avec les assertions de code évaluées, les fonctions de rappels de assert() peuvent être particulièrement utiles, car le code utilisé pour l'assertion est transmis à la fonction rappel en même temps que des informations sur l'emplacement où l'assertion a été effectuée.

Exemple #2 Gérer une assertion échouée avec un gestionnaire personnalisé


<?php
// Activer assert et le rendre silencieux
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Créer une fonction de gestionnaire
function my_assert_handler($file, $line, $code)
{
  echo "<hr>Assertion échouée :
  Fichier '$file'<br />
  Ligne '$line'<br />
  Code '$code'<br /><hr />";
}

// Configurer le rappel
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Faire une assertion qui devrait échouer
$tableau = [];
assert('count($tableau);');
?>
     </programlisting>
     &example.outputs.72;
     <screen>
<![CDATA[
Déprécié : assert() : L'appel de assert() avec un argument de type chaîne est déprécié dans test.php à la ligne 21
<hr>Assertion échouée :
      Fichier 'test.php'<br />
      Ligne '21'<br />
      Code 'count($tableau);'<br /><hr />

Résultat de l'exemple ci-dessus en PHP 7.1 :

<hr>Assertion échouée :
      Fichier 'test.php'<br />
      Ligne '21'<br />
      Code 'count($tableau);'<br /><hr />

Exemple #3 Utiliser un gestionnaire personnalisé pour afficher une description


<?php
// Activer assert et le rendre silencieux
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Créer une fonction de gestionnaire
function my_assert_handler($file, $line, $code, $desc = null)
{
    echo "Assertion échouée à $file:$line : $code";
    if ($desc) {
      echo ": $desc";
    }
    echo "\n";
}

// Configurer le rappel
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Faire une assertion qui devrait échouer
assert('2 < 1');
assert('2 < 1', 'Deux est inférieur à un');
?>

Résultat de l'exemple ci-dessus en PHP 7.2:

Déprécié : assert() : L'appel de assert() avec un argument de type chaîne est déprécié dans test.php à la ligne 21
Assertion échouée à test.php:21 : 2 < 1

Déprécié : assert() : L'appel de assert() avec un argument de type chaîne est déprécié dans test.php à la ligne 22
Assertion échouée à test.php:22 : 2

Résultat de l'exemple ci-dessus en PHP 7.1 :

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

Voir aussi

assert_options() - Définit/récupère différentes options d'assertions