C'est l'occasion de demander l'introduction d'une nouvelle fonction d'assertion :
spip_assert ($condition, $message, $file='assert' ou $opt=_LOG_OPTION, $file='assert' ou $opt=_LOG_OPTION)
$condition : condition normalement satisfaite dans le contexte d'appel
$message : message à loguer si la condition n'est pas satisfaite
$file : fichier de log
$opt : option de log
C'est basé sur un log mais sémantiquement et dans l'usage c'est différent
puisque c'est utilisé pour spéficier de manière descriptive mais programmée :
l'état dans lequel le code doit se trouver.
Par exemple : une fonction ne peut être appelée qu'en var_mode recalcul
On peut l'exprimer en commentaire...
mais on peut aussi l'exprimer avec un assert :
spip_assert ($_GET['var_mode']=='recalcul', "fonc appelée en dehors d'un recalcul var_mode :".$_GET['var_mode'});
ça ne fait rien, ça ne logue rien, normalement, mais si jamais un jour il y avait quelquechose
dans assert.log, on saurait qu'il y a un bug dans le contexte d'appel de cette fonction.
Autre exemple : normalement à cet endroit, si tout a bien été fait en amont ou ailleurs, la variable $arg
est non nulle. On peut l'exprimer en commentaire "$arg est non nulle, car supérieure à 255 dans ce cas ci",
ou "$arg est non nul, testé en amont"
On peut aussi l'exprimer avec un assert :
spip_assert ($arg, "pour fonc : arg nul !");
spip_assert ($arg>255, "pour fonc : arg trop petit devrait être supérieur à 255 car... !");
Normalement, ça ne fait rien, ça ne logue rien, mais si jamais un jour il y avait quelquechose
dans assert.log, on saurait qu'il y a un bug dans le contexte d'appel de cette fonction.
C'est une forme de documentation exacte du code et des contextes à chaque endroit utile sur des projets
un peu complexes et qui doivent être maintenus dans le temps... car ça permet de détecter rapidement
des régressions pas évidentes du code.
En complément au simple spip_log inclu (dont la concaténation est ainsi encapsulée invisible et civilisée),
il y a des traitements complémentaires :
- la pile PHP est systématiquement intégrée au log afin de disposer d'informations sur le contexte d'appel
- si _LOG_EMAIL est passé en paramètre, un mail est envoyé au webmaster
- si LOG_GLOBALES est passé en paramètre, les globales sont aussi loguées
...
spip_assert ne renvoie rien.
Ils sont sans effet sur le flux, et on peut les supprimer si jamais on veut.
spip_assert peut aussi éventuellement être appelé dans un squelette SPIP.
Par exemple dans une noisette dont l'accés est restreint :
[(#SESSION{statut}|=={0minirezo}|spip_assert{Alerte un non admin est dans lanoisette})]
JL