doc-fr/language/functions.xml

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

 <chapter xml:id="language.functions" xmlns="http://docbook.org/ns/docbook">
  <title>Les fonctions</title>

  <sect1 xml:id="functions.user-defined">
   <title>Les fonctions définies par l'utilisateur</title>

   <para>
    Une fonction peut être définie en utilisant la syntaxe suivante :
   </para>
   <para>
    <example>
    <title>Pseudo code pour illustrer l'usage d'une fonction</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
    echo "Exemple de fonction.\n";
    return $retval;
}
?>
]]>
     </programlisting>
    </example>
   </para>

   <simpara>
    Tout code PHP, correct syntaxiquement, peut apparaître
    dans une fonction et dans des définitions de
    <link linkend="keyword.class">classe</link>.
   </simpara>
   <para>
    Les noms de fonctions suivent les mêmes règles que les autres labels en PHP.
    Un nom de fonction valide commence par une lettre ou un souligné, suivi
    par un nombre quelconque de lettres, de nombres ou de soulignés.
    Ces règles peuvent être représentées par l'expression rationnelle suivante :
    <literal>[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*</literal>.
   </para>
   &tip.userlandnaming;
   <simpara>
    Les fonctions n'ont pas besoin d'être définies avant d'être utilisées,
    <emphasis>SAUF</emphasis> lorsqu'une fonction est définie
    conditionnellement, comme montré dans les deux exemples suivants.
   </simpara>
   <para>
    Lorsqu'une fonction est définie de manière conditionnelle, comme dans
    les exemples ci-dessous, leur définition doit <emphasis>précéder</emphasis>
    leur utilisation.
   </para>
   <para>
    <example>
     <title>Fonctions conditionnelles</title>
     <programlisting role="php">
<![CDATA[
<?php

$makefoo = true;

/* Impossible d'appeler foo() ici,
   car cette fonction n'existe pas.
   Mais nous pouvons utiliser bar() */

bar();

if ($makefoo) {
  function foo()
  {
    echo "Je n'existe pas tant que le programme n'est pas passé ici.\n";
  }
}

/* Maitenant, nous pouvons appeler foo()
   car $makefoo est maintenant vrai */

if ($makefoo) foo();

function bar()
{
  echo "J'existe dès de début du programme.\n";
}

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    <example>
     <title>Fonctions dans une autre fonction</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo() 
{
  function bar() 
  {
    echo "Je n'existe pas tant que foo() n'est pas appelé.\n";
  }
}

/* Impossible d'appeler bar() ici
   car il n'existe pas. */

foo();

/* Maintenant, nous pouvons appeler bar(),
   car l'utilisation de foo() l'a rendu
   accessible. */

bar();

?>  
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Toutes les fonctions et classes en PHP ont une portée globale - elles
    peuvent être appelées à l'extérieur d'une fonction si elles ont été définies
    à l'intérieur et vice-versa.
   </para>
   <simpara>
    PHP ne supporte pas le surchargement de fonction, ni la destruction ou la
    redéfinition de fonctions déjà déclarées.
   </simpara>
   <note>
    <simpara>
     Les noms de fonctions sont insensibles à la casse,
     et il est généralement admis que les fonctions doivent
     être appelées avec le nom utilisé dans leur déclaration,
     y compris la casse.
    </simpara>
   </note>
   <simpara>
    Les deux (<link linkend="functions.variable-arg-list">
    liste variable d'arguments de fonction</link> et
    <link linkend="functions.arguments.default">valeurs par défaut
    d'arguments</link>) sont supportés : voir
    les fonctions de références que sont <function>func_num_args</function>,
    <function>func_get_arg</function>, et
    <function>func_get_args</function> pour plus d'informations.
   </simpara>
   <para>
    Il est possible d'appeler des fonctions récursives en PHP. Cependant,
    les appels de méthodes/fonctions récursives avec 100-200 degrés de récursivité
    peuvent remplir la pile et ainsi, terminer le script courant.
    <example>
     <title>Fonctions récursives</title>
     <programlisting role="php">
<![CDATA[
<?php
function recursion($a)
{
    if ($a < 20) {
        echo "$a\n";
        recursion($a + 1);
    }
}
?>
]]>
     </programlisting>
    </example>
   </para>

  </sect1>

  <sect1 xml:id="functions.arguments">
   <title>Les arguments de fonction</title>
   <simpara>
    Des informations peuvent être passées à
    une fonction en utilisant une liste d'arguments, dont chaque
    expression est séparée par une virgule.
   </simpara>
   <para>
    PHP supporte le passage d'arguments par valeur (comportement par défaut), <link
    linkend="functions.arguments.by-reference">le passage par référence</link>, et <link
    linkend="functions.arguments.default">des valeurs d'arguments par défaut</link>.
    <link linkend="functions.variable-arg-list">Une liste variable d'arguments</link>
    est également supportée, voir la documentation sur les fonctions
    <function>func_num_args</function>,
    <function>func_get_arg</function>, et
    <function>func_get_args</function> pour plus d'informations.
   </para>
   <para>
    <example>
     <title>Nombre variable d'argument sous forme de tableau</title>
     <programlisting role="php">
<![CDATA[
<?php
function takes_array($input)
{
    echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
?>
]]>
     </programlisting>
    </example>
   </para>
 
   <sect2 xml:id="functions.arguments.by-reference">
    <title>Passage d'arguments par référence</title>
 
    <simpara>
     Par défaut, les arguments sont passés
     à la fonction par valeur (Ainsi changer la valeur d'un argument dans la fonction  ne
     change pas sa valeur à l'extérieur de la fonction). Si vous voulez que vos fonctions 
     puissent changer la valeur des arguments, vous devez passer ces arguments par référence.
    </simpara>
    <para>
     Si vous voulez qu'un argument soit toujours passé
     par référence, vous pouvez ajouter un '<literal>&amp;</literal>'
     devant l'argument dans la déclaration de la fonction :
    </para>
    <para>
     <example>
      <title>Passage d'arguments par référence</title>
      <programlisting role="php">
<![CDATA[
<?php
function add_some_extra(&$string)
{
    $string .= ', et un peu plus.';
}
$str = 'Ceci est une chaîne';
add_some_extra($str);
echo $str;    // affiche 'Ceci est une chaîne, et un peu plus.'
?>
]]>
      </programlisting>
     </example>
    </para>
 
   </sect2>
 
   <sect2 xml:id="functions.arguments.default">
    <title>Valeur par défaut des arguments</title>
 
    <para>
     Vous pouvez définir comme en C++ des valeurs par
     défaut pour les arguments de type scalaire :
    </para>
    <para>
     <example>
      <title>Valeur par défaut des arguments de fonctions</title>
      <programlisting role="php">
<![CDATA[
<?php
function servir_cafe ($type = "cappuccino")
{
    return "Servir un $type.\n";
}
echo servir_cafe();
echo servir_cafe(null);
echo servir_cafe("espresso");
?>
]]>
      </programlisting>
     </example>
    </para>
 
    <para>
     Le résultat du code ci-dessus est :
    </para>
    <para>
     <screen>
Servir un cappuccino.
Servir un.
Servir un espresso.
     </screen>
    </para>
    <para>
     PHP vous autorise à utiliser des tableaux (<type>array</type>) ainsi que le type spécial
     &null; comme valeur  par défaut, par exemple :
    </para>
    <para>
     <example>
      <title>Utilisation de type non scalaire comme valeur par défaut</title>
      <programlisting role="php">
<![CDATA[
<?php
function servir_cafe($types = array("cappuccino"), $coffeeMaker = NULL)
{
    $device = is_null($coffeeMaker) ? "les mains" : $coffeeMaker;
    return "Préparation d'une tasse de ".join(", ", $types)." avec $device.\n";
}
echo servir_cafe();
echo servir_cafe(array("cappuccino", "lavazza"), "une cafetière");
?>
]]>
      </programlisting>
     </example>
    
    </para>
    <simpara>
     La valeur par défaut d'un argument doit
     obligatoirement être une constante, et ne peut être
     ni une variable, ni un membre de classe, ni un appel de fonction.
    </simpara>
    <para>
     Il est à noter que si vous utilisez des arguments avec
     valeur par défaut avec d'autres sans valeur par défaut,
     les premiers doivent être placés à la suite de tous les paramètres sans
     valeur par défaut. Sinon, cela ne fonctionnera pas.
     Considérons le code suivant :
    </para>
    <para>
     <example>
      <title>Les arguments à valeur par défaut doivent être en premier : erreur</title>
      <programlisting role="php">
<![CDATA[
<?php
function faireunyaourt ($type = "acidophilus", $flavour)
{
    return "Préparer un bol de $type $flavour.\n";
}
 
echo faireunyaourt("framboise");   // ne fonctionne pas comme voulu
?>
]]>
      </programlisting>
     </example>
    </para>
 
    <para>
     Le résultat du code ci-dessus est :
    </para>
    <para>
     <screen>
Warning: Missing argument 2 in call to makeyogurt() in 
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Préparer un bol de framboise.
     </screen>
    </para>
    <para>
     Maintenant comparons l'exemple précédent avec
     l'exemple suivant :
    </para>
    <para>
     <example>
      <title>Les arguments à valeur par défaut doivent être en premier : valide</title>
      <programlisting role="php">
<![CDATA[
<?php
function faireunyaourt ($flavour, $type = "acidophilus")
{
    return "Préparer un bol de $type $flavour.\n";
}
 
echo faireunyaourt ("framboise");   // fonctionne comme voulu
?>
]]>
      </programlisting>
     </example>
    </para>
 
    <para>
     Le résultat du code ci-dessus est :
    </para>
    <para>
     <screen>
Préparer un bol de acidophilus framboise.
     </screen>
    </para>
    
    <note>
     <simpara>
      Depuis PHP 5, les valeurs par défaut peuvent être passées par référence.
     </simpara>
    </note>

   </sect2>

   <sect2 xml:id="functions.variable-arg-list">
    <title>Nombre d'arguments variable</title>

    <simpara>
     PHP 4 et suivants supportent les fonctions à nombre d'arguments variable.
     C'est très simple à utiliser, avec les fonctions
     <function>func_num_args</function>,
     <function>func_get_arg</function> et
     <function>func_get_args</function>.
    </simpara>

    <simpara>
     Aucune syntaxe particulière n'est nécessaire, et
     la liste d'argument doit toujours être fournie
     explicitement avec la définition de la fonction, et se
     comportera normalement.
    </simpara>

   </sect2>

  </sect1>
 
  <sect1 xml:id="functions.returning-values">
   <title>Les valeurs de retour</title>
 
   <para>
    Les valeurs sont renvoyées en utilisant une
    instruction de retour optionnelle. Tous les types de variables
    peuvent être renvoyés, tableaux et objets compris. Cela fait
    que la fonction finit son exécution immédiatement et passe
    le contrôle à la ligne appelante. Voir <function>return</function>
    pour plus d'informations.
   </para>
   <para>
    <example>
     <title>Utilisation de <function>return</function></title>
     <programlisting role="php">
<![CDATA[
<?php
function carre ($num)
{
    return $num * $num;
}
echo carre (4);   // affiche '16'.
?>
]]>
     </programlisting>
    </example>
   </para>
      
   <para>
    Une fonction ne peut pas renvoyer plusieurs valeurs en même temps, mais
    vous pouvez obtenir le même résultat en renvoyant un tableau.
   </para>
   <para>
    <example>
     <title>Retourner un tableau d'une fonction</title>
     <programlisting role="php">
<![CDATA[
<?php
function petit_nombre()
{
    return array (0, 1, 2);
}
list ($zero, $one, $two) = petit_nombre();
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Pour retourner une référence d'une fonction, utilisez
    l'opérateur &amp; aussi bien dans la déclaration de la fonction que dans
    l'assignation de la valeur de retour.
   </para>
   <para>
    <example>
     <title>Retourner une référence d'une fonction</title>
     <programlisting role="php">
<![CDATA[
<?php
function &retourne_reference()
{
    return $uneref;
}

$newref =& retourne_reference();
?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    Pour plus d'informations sur les références, référez-vous à <link
    linkend="language.references">l'explication sur les références</link>.
   </simpara>
  </sect1>
 
  <sect1 xml:id="functions.variable-functions">
   <title>Fonctions variables</title>

   <para>
    PHP supporte le concept de fonctions variables. Cela signifie
    que si le nom d'une variable est suivi de parenthèses,
    PHP recherchera une fonction de même nom,
    et essaiera de l'exécuter. Cela peut servir, entre autres,
    pour faire des fonctions de rappel, des tables de fonctions...
   </para>
   <para>
    Les fonctions variables ne peuvent pas fonctionner avec les
    éléments de langage comme les
    <function>echo</function>, <function>print</function>,
    <function>unset</function>, <function>isset</function>,
    <function>empty</function>, <function>include</function>,
    <function>require</function>
    etc. Vous devez utiliser votre propre gestion de fonctions pour utiliser
    un de ces éléments de langages comme fonctions variables.
   </para>
   <para>
    <example>
     <title>Exemple de fonction variable</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo() {
    echo "dans foo()<br />\n";
}

function bar($arg = '')
{
    echo "Dans bar(); l'argument était '$arg'.<br />\n";
}

// Ceci est une fonction détournée de echo
function echoit($string)
{
    echo $string;
}

$func = 'foo';
$func();        // Appel foo()

$func = 'bar';
$func('test');  // Appel bar()

$func = 'echoit';
$func('test');  // Appel echoit()
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Vous pouvez aussi appeler une méthode d'un objet en utilisant le système des
    fonctions variables.
    <example>
     <title>Exemple de méthode variable</title>
     <programlisting role="php">
<![CDATA[
<?php
class Foo
{
    function Variable()
    {
        $name = 'Bar';
        $this->$name(); // Appelle la méthode Bar()
    }
    
    function Bar()
    {
        echo "C'est Bar";
    }
}

$foo = new Foo();
$funcname = "Variable";
$foo->$funcname();  // Appelle $foo->Variable()

?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Voir aussi
    <function>call_user_func</function>,
    <link linkend="language.variables.variable">les variables variables</link> et
    <function>function_exists</function>.
   </para>
  </sect1>
  
  <sect1 xml:id="functions.internal">
   <title>Fonctions internes</title>
   
   <para>
    PHP dispose de nombreuses fonctions et structures standards. Il y a aussi
    des fonctions qui requièrent des extensions spécifiques de PHP, sans
    lesquelles vous obtiendrez l'erreur fatale
    <literal>undefined function</literal>. Par exemple, pour utiliser les
    fonctions  <link linkend="ref.image">d'images</link>,
    telles que <function>imagecreatetruecolor</function>, vous aurez besoin du
    support de <productname>GD</productname> dans PHP. Ou bien, pour utiliser
    <function>mysql_connect</function>, vous aurez besoin de l'extension
    <link linkend="ref.mysql">MySQL</link>. Il y a des fonctions de base qui
    sont incluses dans toutes les versions de PHP, telles que les fonctions de
    <link linkend="ref.strings">chaînes de caractères</link> et les fonctions
    de <link linkend="ref.var">variables</link>. Utilisez
    <function>phpinfo</function> ou
    <function>get_loaded_extensions</function> pour savoir quelles sont les
    extensions qui sont compilées avec votre PHP. Notez aussi que de
    nombreuses extensions sont activées par défaut, et que le manuel PHP est
    compartimenté par extension. Voyez les chapitres de
    <link linkend="configuration">configuration</link>,
    <link linkend="install">installation</link> ainsi que les
    détails particuliers à chaque extension, pour savoir comment les mettre en place.
   </para>
   <para>
    Lire et comprendre le prototype d'une fonction est décrit dans l'annexe
    <link linkend="about.prototypes">Comment lire la définition d'une
    fonction (prototype)</link>.
    Il est important de comprendre ce qu'une fonction retourne, ou si une
    fonction travaille directement sur la valeur des paramètres fournis. Par
    exemple, <function>str_replace</function> va retourner une chaîne modifiée,
    tandis que <function>usort</function> travaille directement sur la variable
    passée en  paramètre. Chaque page du manuel a des informations spécifiques
    sur chaque fonction, comme le nombre de paramètres, les évolutions de
    spécifications, les valeurs retournées en cas de succès ou d'échec, et la
    disponibilité en fonction des versions. Bien connaître ces différences,
    parfois subtiles, est crucial pour bien programmer en PHP.
   </para>
   <note>
    <simpara>
     Si les paramètres donnés à une fonction ne sont pas corrects, comme le fait
     de passer un &array; alors qu'une &string; est attendue, la valeur retournée
     de la fonction est indéfinie. Dans ce cas, la fonction retournera la plupart
     du temps une valeur &null; mais ce n'est juste qu'une convention et
     ne peut être considéré comme une certitude.
    </simpara>
   </note>
   <para>
    Voir aussi
    <function>function_exists</function>,
    <link linkend="funcref">l'index des fonctions</link>,
    <function>get_extension_funcs</function> et
    <function>dl</function>.
   </para>
  </sect1>

  <sect1 xml:id="functions.anonymous">
   <title>Fonctions anonymes</title>
   <para>
    Les fonctions anonymes permettent la création de fonctions 
    sans préciser leur nom. Elles sont particulièrement utiles
    comme <link linkend="language.types.callback">fonction de rappel</link>,
    mais leur utilisation n'est pas limitée à ce seul usage.
   </para>
   <para>
    <example>
     <title>Exemples avec des fonctions anonymes</title>
     <programlisting role="php">
<![CDATA[
<?php
echo preg_replace_callback('~-([a-z])~', function ($match) {
    return strtoupper($match[1]);
}, 'bonjour-le-monde');
// outputs bonjourLeMonde
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    Les fonctions anonymes sont implémentées en interne par 
    la classe prédéfinie 
    <link linkend="reserved.classes.closure"><literal>Closure</literal></link>.
   </para>
   <note>
    <para>
     Les fonctions anonymes sont disponibles depuis PHP 5.3.0.
    </para>
   </note>
   </sect1>
 

 </chapter>
 
<!-- 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
-->