doc-fr/reference/info/functions/assert.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.21 $ -->
<!-- EN-Revision: 1.12 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->

<refentry xml:id="function.assert" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>assert</refname>
  <refpurpose>Vérifie si une assertion est fausse</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>assert</methodname>
   <methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>assert</function> va vérifier l'assertion
   <parameter>assertion</parameter> et prendre la mesure appropriée
   si le résultat est &false;.
  </para>
  <para>
   Si <parameter>assertion</parameter> est donnée sous la forme
   d'une chaîne, elle sera évaluée comme un code PHP
   par la fonction <function>assert</function>. Les avantages de ce type
   d'assertion sont d'être moins lourd si la vérification
   d'assertion est désactivée, et les messages contenant l'assertion
   lorsque l'assertion échoue. Cela signifie que si vous passez une condition
   booléenne en tant qu'assertion, cette condition ne sera pas considérée
   comme un paramètre par la fonction d'assertion que vous avez définie avec
   la fonction <function>assert_options</function>, la condition est convertie
   en &string; avant l'appel à ce gestionnaire de fonction, et le booléen &false;
   sera converti en &string; vide.
  </para>
  <para>
   Il est recommandé de n'utiliser les assertions que comme outil de
   déboguage. Vous pouvez les utiliser pour les vérifications
   d'usage : ces conditions doivent normalement être vraies, et indiquer
   une erreur de programmation si ce n'est pas le cas. Vous pouvez aussi
   vérifier la présence de certaines extensions ou
   limitations du système.
  </para>
  <para>
   Les assertions ne doivent pas être utilisées pour faire des
   opérations de vérifications en production, comme
   des vérifications de valeur d'argument. En conditions normales,
   votre code doit être en état de fonctionner si la
   vérification d'assertion est désactivée.
  </para>
  <para>
   Le comportement de <function>assert</function> peut être configuré
   par <function>assert_options</function> ou par les directives 
   de configuration décrites dans la page de manuel de cette fonction.
  </para>
  <para>
   La fonction <function>assert_options</function> et la directive
   ASSERT_CALLBACK permettent de configurer une fonction qui sera appelée
   lorsque l'assertion échoue.
  </para>
  <para>
   Les fonctions de rappel pour <function>assert</function> sont
   particulièrement utiles pour bâtir des suites de tests automatiques,
   car elles vous permettent de capturer facilement le code passé à l'assertion,
   ainsi que des informations sur le lieu et le moment de l'assertion.
   Même si ces informations peuvent être appelées par d'autres méthodes,
   les assertions sont plus rapides et plus faciles.
  </para>
  <para>
   La fonction de rappel doit accepter trois arguments. Le premier
   contient le nom du fichier qui a vu l'assertion échouer. Le second
   contient le numéro de ligne dans le fichier précédent.
   Le troisième argument contient l'expression qui a échoué (s'il
   y en a : les valeurs littérales comme 1 ou "deux" ne seront
   pas passées par cet argument).
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>assertion</parameter></term>
     <listitem>
      <para>
       L'assertion.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &false; si l'assertion est fausse, &true; sinon.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Gestion des assertions avec un gestionnaire personnalisé</title>
    <programlisting role="php">
<![CDATA[
<?php
// Activation des assertions et mise en mode discret
assert_options(ASSERT_ACTIVE, 1);
assert_options(ASSERT_WARNING, 0);
assert_options(ASSERT_QUIET_EVAL, 1);

// Création d'un gestionnaire d'assertions
function my_assert_handler($file, $line, $code)
{
    echo "<hr>Échec de l'assertion :
        File '$file'<br />
        Line '$line'<br />
        Code '$code'<br /><hr />";
}

// Configuration de la méthode de callback
assert_options(ASSERT_CALLBACK, 'my_assert_handler');

// Utilisation d'une assertion qui va échouer
assert('mysql_query("")');
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>assert_options</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->