assert.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 27dcb487a7e9c0f04559522a6d2aacf860d622cd Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.assert" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>assert</refname>
  <refpurpose>Vérifie une assertion</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>assert</methodname>
   <methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>Throwable</type><type>string</type><type>null</type></type><parameter>description</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>assert</function>
   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.
  </para>
  <para>
   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.
  </para>
  <para>
   Comme les assertions peuvent être configurées pour être éliminées, elles ne doivent
   <emphasis>pas</emphasis> ê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.
  </para>
  <para>
   <function>assert</function> vérifiera que l'attente donnée dans
   <parameter>assertion</parameter> 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 <function>assert</function>.
  </para>
  <para>
   Le comportement de <function>assert</function> est dicté par les paramètres INI suivants :
   <table>
    <title>Assert &ConfigureOptions;</title>
     <tgroup cols="4">
     <thead>
      <row>
       <entry>&Name;</entry>
       <entry>&Default;</entry>
       <entry>&Description;</entry>
       <entry>&Changelog;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><link linkend="ini.zend.assertions">zend.assertions</link></entry>
       <entry><literal>1</literal></entry>
       <entry>
        <simplelist>
         <member>
          <literal>1</literal> : génère et exécute le code (mode développement)
         </member>
         <member>
          <!-- TODO: look up the RFC to figure out why you'd want this -->
          <literal>0</literal> : génère le code mais l'évite au moment de l'exécution
         </member>
         <member>
          <literal>-1</literal> : ne génère pas le code (mode production)
         </member>
        </simplelist>
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.active">assert.active</link></entry>
       <entry>&true;</entry>
       <entry>
        Si &false;, <function>assert</function> ne vérifie pas l'attente
        et retourne toujours &true;, sans condition.
       </entry>
       <entry>
        Obsolète à partir de PHP 8.3.0.
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.callback">assert.callback</link></entry>
       <entry>&null;</entry>
       <entry>
        <para>
         Une fonction définie par l'utilisateur à appeler lorsqu'une assertion échoue.
         Sa signature devrait être :
         <methodsynopsis role="procedural">
          <type>void</type><methodname>assert_callback</methodname>
          <methodparam><type>string</type><parameter>file</parameter></methodparam>
          <methodparam><type>int</type><parameter>line</parameter></methodparam>
          <methodparam><type>null</type><parameter>assertion</parameter></methodparam>
          <methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
         </methodsynopsis>
        </para>
       </entry>
       <entry>
        <para>
         Antérieur à PHP 8.0.0, la signature de la fonction de rappel devrait être :
         <methodsynopsis role="procedural">
          <type>void</type><methodname>assert_callback</methodname>
          <methodparam><type>string</type><parameter>file</parameter></methodparam>
          <methodparam><type>int</type><parameter>line</parameter></methodparam>
          <methodparam><type>string</type><parameter>assertion</parameter></methodparam>
          <methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
         </methodsynopsis>
        </para>
        <simpara>
         Obsolète à partir de PHP 8.3.0.
        </simpara>
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.exception">assert.exception</link></entry>
       <entry>&true;</entry>
       <entry>
        Si &true;, lancera une <classname>AssertionError</classname> si l'attente n'est pas respectée.
       </entry>
       <entry>
        Obsolète à partir de PHP 8.3.0.
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.bail">assert.bail</link></entry>
       <entry>&false;</entry>
       <entry>
        Si &true;, interrompra l'exécution du script PHP si l'attente n'est pas respectée.
       </entry>
       <entry>
        Obsolète à partir de PHP 8.3.0.
       </entry>
      </row>
      <row>
       <entry><link linkend="ini.assert.warning">assert.warning</link></entry>
       <entry>&true;</entry>
       <entry>
        Si &true;, émettra un <constant>E_WARNING</constant> si l'attente n'est pas respectée.
        Ce paramètre INI est inefficace si
        <link linkend="ini.assert.exception">assert.exception</link>
        est activé.
       </entry>
       <entry>
        Obsolète à partir de PHP 8.3.0.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>assertion</parameter></term>
     <listitem>
      <para>
       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é.
      </para>

      <warning>
       <para>
        Antérieur à PHP 8.0.0, si <parameter>assertion</parameter> était une
        <type>string</type>, elle était interprétée comme du code PHP et exécutée via
        <function>eval</function>.
        Cette chaîne était transmise à la fonction de rappel en tant que troisième argument.
        Ce comportement était <emphasis>OBSOLÈTE</emphasis> dans PHP 7.2.0,
        et est <emphasis>SUPPRIMÉ</emphasis> à partir de PHP 8.0.0
       </para>
      </warning>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>description</parameter></term>
     <listitem>
      <para>
       Si <parameter>description</parameter> est une instance de
       <classname>Throwable</classname>, elle sera lancée uniquement si
       <parameter>assertion</parameter> est exécutée et échoue.
       <note>
        <para>
         À partir de PHP 8.0.0, cela est fait <emphasis>avant</emphasis> d'appeler
         la fonction de rappel d'assertion éventuellement défini
        </para>
       </note>
       <note>
        <para>
         À partir de PHP 8.0.0, l'objet &object; sera lancé indépendamment de la configuration de
         <link linkend="ini.assert.exception">assert.exception</link>.
        </para>
       </note>
       <note>
        <para>
         À partir de PHP 8.0.0, le paramètre
         <link linkend="ini.assert.bail">assert.bail</link>
         n'a aucun effet dans ce cas.
        </para>
       </note>
      </para>
      <para>
       Si <parameter>description</parameter> est une &string;, 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'<parameter>assertion</parameter> échoue.
      </para>
      <para>
       Si <parameter>description</parameter> est omis.
       <!-- Cela ne se produit pas si &null; est passé ... -->
       Une description par défaut équivalente au code source de l'appel de
       <function>assert</function> est créée au moment de la compilation.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>assert</function> renverra toujours &true; si au moins l'une des conditions suivantes est vraie :
  </para>
  <simplelist>
   <member><literal>zend.assertions=0</literal></member>
   <member><literal>zend.assertions=-1</literal></member>
   <member><literal>assert.exception=1</literal></member>
   <member><literal>assert.bail=1</literal></member>
   <member>Un objet d'exception personnalisé est passé à <parameter>description</parameter>.</member>
  </simplelist>
  <para>
   Si aucune des conditions n'est vraie, <function>assert</function> renverra &true; si
   <parameter>assertion</parameter> est vrai, et &false; sinon.
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.3.0</entry>
       <entry>
        Toutes les configurations INI <literal>assert.</literal> ont été dépréciées.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        La fonction <function>assert</function> n'évaluera plus les arguments de type string,
        au lieu de cela, ils seront traités comme tout autre argument.
        <code>assert($a == $b)</code> devrait être utilisé à la place du <code>assert('$a == $b')</code>.
        La directive <literal>assert.quiet_eval</literal> &php.ini; et la constante <constant>ASSERT_QUIET_EVAL</constant>
        ont également été supprimées, car elles n'auraient plus aucun effet.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Si <parameter>description</parameter> est une instance de
        <classname>Throwable</classname>, l'objet est lancé si l'assertion échoue, indépendamment de la valeur de
        <link linkend="ini.assert.exception">assert.exception</link>.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Si <parameter>description</parameter> est une instance de
        <classname>Throwable</classname>, aucune fonction de rappel utilisateur
        n'est appelée même si elle est définie.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Déclarer une fonction qui s'appelle <literal>assert()</literal> à
        l'intérieur d'un espace de nom n'est plus autorisé, et génère
        une <constant>E_COMPILE_ERROR</constant>.
       </entry>
      </row>
      <row>
       <entry>7.3.0</entry>
       <entry>
        Déclarer une fonction qui s'appelle <literal>assert()</literal> à
        l'intérieur d'un espace de nom est devenue obsolète. De telles
        déclarations génèrent désormais une <constant>E_DEPRECATED</constant>.
       </entry>
      </row>
      <row>
       <entry>7.2.0</entry>
       <entry>
        L'utilisation d'une &string; en tant qu'<parameter>assertion</parameter> est
        est devenue obsolète. Ceci émet désormais une notice 
        <constant>E_DEPRECATED</constant> quand 
        <link linkend="ini.assert.active">assert.active</link> et
        <link linkend="ini.zend.assertions">zend.assertions</link> sont tous
        les deux définit à <literal>1</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
   <example>
    <title>Exemple d'<function>assert</function></title>
    <programlisting role="php">
<![CDATA[
<?php
assert(1 > 2);
echo 'Hi!';
?>
]]>
    </programlisting>
    <para>
     Si les assertions sont activées (<link linkend="ini.zend.assertions"><literal>zend.assertions=1</literal></link>)
     l'exemple ci-dessus afficherait :
    </para>
    <screen>
<![CDATA[
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
]]>
    </screen>
    <para>
     Si les assertions sont désactivées (<literal>zend.assertions=0</literal> ou <literal>zend.assertions=-1</literal>)
     l'exemple ci-dessus afficherait :
    </para>
    <screen>
<![CDATA[
Hi!
]]>
    </screen>
   </example>
   <example>
    <title>Utilisation d'un message personnalisé</title>
    <programlisting role="php">
<![CDATA[
<?php
assert(1 > 2, "Expected one to be greater than two");
echo 'Hi!';
?>
]]>
    </programlisting>
    <para>
     Si les assertions sont activées, l'exemple ci-dessus affichera :
     l'exemple ci-dessus afficherait :
    </para>
    <screen>
<![CDATA[
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
]]>
    </screen>
    <para>
     Si les assertions sont désactivées, l'exemple ci-dessus affichera :
     l'exemple ci-dessus afficherait :
    </para>
    <screen>
<![CDATA[
Hi!
]]>
    </screen>
    </example>
    <example>
     <title>Utilisation d'une classe d'exception personnalisée</title>
     <programlisting role="php">
      <![CDATA[
      <?php
      class ArithmeticAssertionError extends AssertionError {}

      assert(1 > 2, new ArithmeticAssertionError("Expected one to be greater than two"));
      echo 'Hi!';
      ]]>
     </programlisting>
    <para>
     Si les assertions sont activées, l'exemple ci-dessus affichera :
     l'exemple ci-dessus afficherait :
    </para>
    <screen>
<![CDATA[
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
]]>
    </screen>
     <para>
      Si les assertions sont désactivées, l'exemple ci-dessus affichera :
     </para>
     <screen>
<![CDATA[
Hi!
]]>
     </screen>
    </example>
 </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:"~/.phpdoc/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
-->