mirror of
https://github.com/macintoshplus/doc-fr.git
synced 2026-03-26 09:52:17 +01:00
488 lines
16 KiB
XML
488 lines
16 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: 59af09939ab6e191c9836ea3b33b934e1a99a263 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;
|
|
<para>PHP 5 et 7</para>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>assert</methodname>
|
|
<methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>PHP 7</para>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>assert</methodname>
|
|
<methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
|
|
<methodparam choice="opt"><type>Throwable</type><parameter>exception</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>
|
|
<refsect2>
|
|
<title>Assertions traditionnelles (PHP 5 et 7)</title>
|
|
<para>
|
|
Si <parameter>assertion</parameter> est donnée sous la forme d'une &string;,
|
|
elle sera évaluée en tant que code PHP par <function>assert</function>.
|
|
Si une condition booléenne est donnée en tant qu'<parameter>assertion</parameter>,
|
|
cette condition ne sera pas considérée comme un paramètre par la fonction
|
|
d'assertion que vous avez définie avec <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ébogage. 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
|
|
<constant>ASSERT_CALLBACK</constant> 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). Les utilisateurs de PHP 5.4.8 ou supérieur
|
|
peuvent également fournir un quatrième argument optionnel, qui contiendra
|
|
la <parameter>description</parameter> fournie à la fonction
|
|
<function>assert</function>, s'il est défini.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 xml:id="function.assert.expectations">
|
|
<title>Expectations (PHP 7 seulement)</title>
|
|
<para>
|
|
<function>assert</function> est une construction de langage en PHP 7,
|
|
autorisé pour la définition des expectations : les assertions qui prennent
|
|
effet dans les environnements de développement et de test, mais qui sont
|
|
optimisées de sorte à avoir un coût zéro en production.
|
|
</para>
|
|
<para>
|
|
Bien que <function>assert_options</function> peut toujours être utilisé
|
|
pour contrôler le comportement tel que décrit ci-dessus pour des raisons
|
|
de compatibilité ascendante, le code purement PHP 7 doit utiliser les deux
|
|
nouvelles directives de configuration pour contrôler le comportement de
|
|
la fonction <function>assert</function> et ne pas appeler la fonction
|
|
<function>assert_options</function>.
|
|
</para>
|
|
<table>
|
|
<title>
|
|
Les directives de configuration PHP 7 pour <function>assert</function>
|
|
</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Directive</entry>
|
|
<entry>Valeur par défaut</entry>
|
|
<entry>Valeurs possibles</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.exception">assert.exception</link>
|
|
</entry>
|
|
<entry><literal>0</literal></entry>
|
|
<entry>
|
|
<simplelist>
|
|
<member>
|
|
<literal>1</literal> : lancé lorsqu'une assertion échoue, soit en lançant
|
|
l'objet fourni par l'<parameter>exception</parameter>, soit en lançant
|
|
un nouvel objet <classname>AssertionError</classname> si
|
|
l'<parameter>exception</parameter> n'a pas été fournit
|
|
</member>
|
|
<member>
|
|
<literal>0</literal> : utilise ou génère un
|
|
<classname>Throwable</classname> tel que décrit ci-dessus, mais ne génère
|
|
qu'une alerte basée sur cet objet plutôt que de le lancer
|
|
(compatible avec le comportement de PHP 5)
|
|
</member>
|
|
</simplelist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>assertion</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
L'assertion. En PHP 5, ceci peut être soit une chaîne de caractères
|
|
à évaluer, soit un &boolean; à tester. En PHP 7, ceci peut également
|
|
être toute expression qui retourne une valeur, qui peut être exécuté
|
|
et le résultat utilisé pour indiquer si l'assertion a réussi ou a échoué.
|
|
</para>
|
|
|
|
<warning>
|
|
<para>
|
|
L'utilisation d'une &string; en tant qu'<parameter>assertion</parameter> est
|
|
<emphasis>OBSOLÈTE</emphasis> à partir de PHP 7.2 et <emphasis>SUPPRIMÉE</emphasis> à partir de PHP 8.0.0.
|
|
</para>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>description</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Une description optionnelle, qui sera incluse dans le message
|
|
d'échec si l'<parameter>assertion</parameter> échoue.
|
|
À partir de PHP 7, si aucune description est fournie, une description
|
|
par défaut identique au code source de l'invocation de
|
|
<function>assert</function> est fournie.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>exception</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
En PHP 7, le second paramètre peut être un objet
|
|
<classname>Throwable</classname> au lieu d'une chaîne descriptive,
|
|
auquel cas, ceci sera un objet qui sera lancé si l'assertion échoue et que
|
|
la directive de configuration
|
|
<link linkend="ini.assert.exception">assert.exception</link> est activée.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&false; si l'assertion est fausse, &true; 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.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>
|
|
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 telle
|
|
déclarations génère 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>
|
|
<row>
|
|
<entry>7.0.0</entry>
|
|
<entry>
|
|
<function>assert</function> est maintenant une construction de langage
|
|
et non une fonction. <parameter>assertion</parameter> peut maintenant
|
|
être une expression. Le second paramètre est maintenant interprété
|
|
soit comme une <parameter>exception</parameter> (si un objet
|
|
<classname>Throwable</classname> est fourni), soit comme une
|
|
<parameter>description</parameter> supportée depuis PHP 5.4.8 et ultérieur.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<refsect2>
|
|
<title>Assertions traditionnelles (PHP 5 et 7)</title>
|
|
<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>
|
|
<para>
|
|
<example>
|
|
<title>Utilisation d'un gestionnaire personnalisé pour afficher une description</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Activation de l'assertion et on le rend silencieux
|
|
assert_options(ASSERT_ACTIVE, 1);
|
|
assert_options(ASSERT_WARNING, 0);
|
|
assert_options(ASSERT_QUIET_EVAL, 1);
|
|
|
|
// Création d'une fonction de gestionnaire
|
|
function my_assert_handler($file, $line, $code, $desc = null)
|
|
{
|
|
echo "Echec de l'assertion : $file:$line: $code";
|
|
if ($desc) {
|
|
echo ": $desc";
|
|
}
|
|
echo "\n";
|
|
}
|
|
|
|
// Définition de la fonction de rappel
|
|
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
|
|
|
|
// Effectue une assertion qui doit échouer
|
|
assert('2 < 1');
|
|
assert('2 < 1', 'Deux est inférieur à un');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
Echec de l'assertion : test.php:21: 2 < 1
|
|
Echec de l'assertion : test.php:22: 2 < 1: Deux est inférieur à un
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>Expectations (PHP 7 seulement)</title>
|
|
<example>
|
|
<title>Expectations sans exception personalisée</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
assert(true == false);
|
|
echo 'Hi!';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
Avec <link linkend="ini.zend.assertions">zend.assertions</link> défini à 0,
|
|
l'exemple ci-dessus afficherait :
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Avec <link linkend="ini.zend.assertions">zend.assertions</link> défini à 1
|
|
et <link linkend="ini.assert.exception">assert.exception</link> défini à 0,
|
|
l'exemple ci-dessus afficherait :
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Warning: assert(): assert(true == false) failed in - on line 2
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
AVec <link linkend="ini.zend.assertions">zend.assertions</link> défini à 1
|
|
et <link linkend="ini.assert.exception">assert.exception</link> défini à 1,
|
|
l'exemple ci-dessus afficherait :
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Fatal error: Uncaught AssertionError: assert(true == false) in -:2
|
|
Stack trace:
|
|
#0 -(2): assert(false, 'assert(true == ...')
|
|
#1 {main}
|
|
thrown in - on line 2
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<example>
|
|
<title>Expectations avec une exception personalisée</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class CustomError extends AssertionError {}
|
|
|
|
assert(true == false, new CustomError('True is not false!'));
|
|
echo 'Hi!';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
Avec <link linkend="ini.zend.assertions">zend.assertions</link> défini à 0,
|
|
l'exemple ci-dessus afficherait :
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Avec <link linkend="ini.zend.assertions">zend.assertions</link> défini à 1
|
|
et <link linkend="ini.assert.exception">assert.exception</link> défini à 0,
|
|
l'exemple ci-dessus afficherait :
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Warning: assert(): CustomError: True is not false! in -:4
|
|
Stack trace:
|
|
#0 {main} failed in - on line 4
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Avec <link linkend="ini.zend.assertions">zend.assertions</link> défini à 1
|
|
et <link linkend="ini.assert.exception">assert.exception</link> défini à 1,
|
|
l'exemple ci-dessus afficherait :
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Fatal error: Uncaught CustomError: True is not false! in -:4
|
|
Stack trace:
|
|
#0 {main}
|
|
thrown in - on line 4
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</refsect2>
|
|
</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
|
|
-->
|