PHP 8.4.0 RC4 available for testing

assert

(PHP 4, PHP 5, PHP 7, PHP 8)

assertVérifie une assertion

Description

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

assert() permets 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. Obsolète à partir de PHP 8.3.0.
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

Obsolète à partir de PHP 8.3.0.
assert.exception true Si true, lancera une AssertionError si l'attente n'est pas respectée. Obsolète à partir de PHP 8.3.0.
assert.bail false Si true, interrompra l'exécution du script PHP si l'attente n'est pas respectée. Obsolète à partir de PHP 8.3.0.
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é. Obsolète à partir de PHP 8.3.0.

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

assert() renverra toujours true si au moins l'une des conditions suivantes est vraie :

  • zend.assertions=0
  • zend.assertions=-1
  • assert.exception=1
  • assert.bail=1
  • Un objet d'exception personnalisé est passé à description.

Si aucune des conditions n'est vraie, assert() renverra true si assertion est vrai, et false sinon.

Historique

Version Description
8.3.0 Toutes les configurations INI assert. ont été dépréciées.
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

Exemple #1 Exemple d'assert()

<?php
assert
(1 > 2);
echo
'Hi!';
?>

Si les assertions sont activées (zend.assertions=1) l'exemple ci-dessus afficherait :

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

Si les assertions sont désactivées (zend.assertions=0 ou zend.assertions=-1) l'exemple ci-dessus afficherait :

Hi!

Exemple #2 Utilisation d'un message personnalisé

<?php
assert
(1 > 2, "Expected one to be greater than two");
echo
'Hi!';
?>

Si les assertions sont activées, l'exemple ci-dessus affichera : l'exemple ci-dessus afficherait :

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

Si les assertions sont désactivées, l'exemple ci-dessus affichera : l'exemple ci-dessus afficherait :

Hi!

Exemple #3 Utilisation d'une classe d'exception personnalisée

<?php
class ArithmeticAssertionError extends AssertionError {}

assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
echo
'Hi!';

Si les assertions sont activées, l'exemple ci-dessus affichera : l'exemple ci-dessus afficherait :

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

Si les assertions sont désactivées, l'exemple ci-dessus affichera :

Hi!

Voir aussi

add a note

User Contributed Notes 2 notes

up
33
hodgman at ali dot com dot au
16 years ago
As noted on Wikipedia - "assertions are primarily a development tool, they are often disabled when a program is released to the public." and "Assertions should be used to document logically impossible situations and discover programming errors— if the 'impossible' occurs, then something fundamental is clearly wrong. This is distinct from error handling: most error conditions are possible, although some may be extremely unlikely to occur in practice. Using assertions as a general-purpose error handling mechanism is usually unwise: assertions do not allow for graceful recovery from errors, and an assertion failure will often halt the program's execution abruptly. Assertions also do not display a user-friendly error message."

This means that the advice given by "gk at proliberty dot com" to force assertions to be enabled, even when they have been disabled manually, goes against best practices of only using them as a development tool.
up
9
sven at rtbg dot de
8 months ago
With the current changes made in PHP 8.3 (deprecating the INI settings affecting assertions) and the increasing amount of open source libraries utilizing `assert()` as an easy means to ensure obscure return cases of PHP core function calls are in fact not triggered (e.g. no NULL or FALSE has been returned, but the useful value), the comment made about assertions only being a tool used during development should be considered invalid.

In addition, static code analysis tools use the knowledge gained from `assert($x instanceof MyClass)` to know the type or types that are possible.

Assertions are actively being used in production code, they are useful, and disabling them would only gain minimal performance benefits because the asserted expression usually is very small.

Use this tool where applicable!
To Top