archived-doc-fr/language/types/callable.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 312c0c7b39d0722c419f6784cbda24823220dfb3 Maintainer: Fan2Shrek Status: ready -->
<!-- Reviewed: yes Maintainer: girgias -->
<!-- CREDITS: DavidA -->
<sect1 xml:id="language.types.callable">
 <title>Callables</title>

 <simpara>
   Un callable est une référence à une fonction ou une méthode qui est
   passée à une autre fonction en tant qu'argument.
   Elles sont représentées avec la déclaration de type <type>callable</type>.
 </simpara>
 <informalexample>
  <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
function foo(callable $callback) {
    $callback();
}
?>
]]>
  </programlisting>
 </informalexample>

 <simpara>
  Certaines fonctions acceptent des fonctions de rappel en tant que paramètre, par exemple
  <function>array_map</function>, <function>usort</function>, ou
  <function>preg_replace_callback</function>.
 </simpara>

 <sect2 xml:id="language.types.callable.passing">
  <title>Création de callables</title>

  <simpara>
   Un callable est un type qui représente quelque chose qui peut être invoqué.
   Les callables peuvent être passés en tant qu'arguments aux fonctions ou méthodes qui
   attendent un paramètre callback ou ils peuvent être invoqués directement.
   Le type <type>callable</type> ne peut pas être utilisé comme déclaration de type pour les
   propriétés. À la place, utiliser une déclaration de type <classname>Closure</classname>.
  </simpara>

  <simpara>
   Les callables peuvent être créés de plusieurs façons différentes :
  </simpara>

  <itemizedlist>
   <listitem>
    <simpara>Objet <classname>Closure</classname></simpara>
   </listitem>
   <listitem>
    <simpara>Une &string; contenant le nom d'une fonction ou d'une méthode</simpara>
   </listitem>
   <listitem>
    <simpara>
     Un &array; contenant le nom d'une classe ou un <type>object</type>
     dans l'index 0 et le nom de la méthode dans l'index 1
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     Un &object; implémentant la méthode magique
     <link linkend="object.invoke">__invoke()</link>
    </simpara>
   </listitem>
  </itemizedlist>

  <simpara>
   Un objet <classname>Closure</classname> peut être créé en utilisant
   la syntaxe <link linkend="functions.anonymous">function anonyme</link>,
   la syntaxe <link linkend="functions.arrow">function fléchée</link>,
   la syntaxe <link linkend="functions.first_class_callable_syntax">callable de première
   classe</link>, ou la méthode <methodname>Closure::fromCallable</methodname>.
  </simpara>

  <note>
   <simpara>
    La syntaxe <link linkend="functions.first_class_callable_syntax">callable de première
    classe</link> est disponible uniquement à partir de PHP 8.1.0.
   </simpara>
  </note>

  <example>
   <title>
    Exemple de callback utilisant une <classname>Closure</classname>
   </title>
   <programlisting role="php">
<![CDATA[
<?php
// Utilisant la syntaxe de fonction anonyme
$double1 = function ($a) {
    return $a * 2;
};

// Utilisant la syntaxe callable de première classe
function double_function($a) {
    return $a * 2;
}
$double2 = double_function(...);

// Utilisant la syntaxe de fonction fléchée
$double3 = fn($a) => $a * 2;

// Utilisant la méthode Closure::fromCallable
$double4 = Closure::fromCallable('double_function');

// Utilisant la closure comme callback pour
// doubler la taille de chaque élément dans notre range
$new_numbers = array_map($double1, range(1, 5));
print implode(' ', $new_numbers) . PHP_EOL;

$new_numbers = array_map($double2, range(1, 5));
print implode(' ', $new_numbers) . PHP_EOL;

$new_numbers = array_map($double3, range(1, 5));
print implode(' ', $new_numbers) . PHP_EOL;

$new_numbers = array_map($double4, range(1, 5));
print implode(' ', $new_numbers);

?>
]]>
   </programlisting>
   &example.outputs.81;
   <screen>
<![CDATA[
2 4 6 8 10
2 4 6 8 10
2 4 6 8 10
2 4 6 8 10
]]>
   </screen>
  </example>

  <simpara>
   Un callable peut également être une string contenant le nom d'une fonction ou une méthode
   statique.
   N'importe quelle fonction intégrée ou définie par l'utilisateur peut être utilisée, à l'exception des constructions de langage
   telles que : <function>array</function>, <function>echo</function>,
   <function>empty</function>, <function>eval</function>,
   <function>isset</function>,
   <function>list</function>, <function>print</function> ou
   <function>unset</function>.
  </simpara>

  <simpara>
   Les méthodes de classes statiques peuvent être utilisées sans instancier un
   <type>object</type> de cette classe en créant soit un tableau avec
   le nom de la classe à l'index 0 et le nom de la méthode à l'index 1, ou en utilisant
   la syntaxe spéciale avec l'opérateur de résolution de portée
   <literal>::</literal>, comme dans <literal>'ClassName::methodName'</literal>.
  </simpara>

  <simpara>
   Une méthode d'un <type>object</type> instancié peut être un callable
   lorsqu'elle est fournie sous forme de tableau avec le <type>object</type> à l'index 0 et
   le nom de la méthode à l'index 1.
  </simpara>

  <simpara>
   La principale différence entre un objet <classname>Closure</classname> et le
   type <type>callable</type> est que l'objet <classname>Closure</classname>
   est indépendant du scope et peut tout le temps être invoqué, alors qu'un type callable peut
   être dépendant du scope et ne peut être invoqué directement.
   <classname>Closure</classname> est la méthode préférée pour créer des callables.
  </simpara>

  <note>
   <simpara>
    Tandis que les objets <classname>Closure</classname> sont liés au scope
    où ils sont créés, les callables référençant des méthodes de classes sous forme
    de chaînes de caractères ou de tableaux sont résolus dans le scope où ils sont appelés.
    Pour créer un callable à partir d'une méthode privée ou protégée, qui peut ensuite être
    invoqué depuis l'extérieur de la classe, utiliser
    <methodname>Closure::fromCallable</methodname> ou la 
    <link linkend="functions.first_class_callable_syntax">syntaxe callable de
    première classe</link>
   </simpara>
  </note>

  <simpara>
   PHP permet la création de callables qui peuvent être utilisés en tant qu'argument
   de callback mais qui ne peuvent pas être appelés directement.
   Il s'agit de callables dépendants du contexte qui référencent une méthode de classe
   dans la hiérarchie d'héritage d'une classe, par exemple
   <literal>'parent::method'</literal> ou <literal>["static", "method"]</literal>.
  </simpara>

  <note>
   <simpara>
    À partir de PHP 8.2.0, les callables dépendants du contexte
    sont dépréciés. Supprimez la dépendance au contexte en remplaçant
    <literal>'parent::method'</literal> par
    <literal>parent::class . '::method'</literal> ou utiliser la
    <link linkend="functions.first_class_callable_syntax">syntaxe callable de
    première classe</link>.
   </simpara>
  </note>

  <example>
   <title>
    Appel de différents types de callables avec <function>call_user_function</function>
   </title>
   <programlisting role="php">
<![CDATA[
<?php

// Un exemple de fonction de rappel
function my_callback_function() {
    echo 'hello world!', PHP_EOL;
}

// Un exemple de méthode de rappel
class MyClass {
    static function myCallbackMethod() {
        echo 'Hello World!', PHP_EOL;
    }
}

// Type 1: Callback simple
call_user_func('my_callback_function');

// Type 2: Appel de méthode de classe statique
call_user_func(['MyClass', 'myCallbackMethod']);

// Type 3: Appel de méthode d'objet
$obj = new MyClass();
call_user_func([$obj, 'myCallbackMethod']);

// Type 4: Appel de méthode de classe statique
call_user_func('MyClass::myCallbackMethod');

// Type 5: Appel de méthode de classe statique en utilisant le mot-clé ::class
call_user_func([MyClass::class, 'myCallbackMethod']);

// Type 6: Appel de méthode de classe statique relative
class A {
    public static function who() {
        echo 'A', PHP_EOL;
    }
}

class B extends A {
    public static function who() {
        echo 'B', PHP_EOL;
    }
}

call_user_func(['B', 'parent::who']); // deprecated as of PHP 8.2.0

// Type 7: Les objets implémentant __invoke peuvent être utilisés en tant que callables
class C {
    public function __invoke($name) {
        echo 'Hello ', $name;
    }
}

$c = new C();
call_user_func($c, 'PHP!');
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
hello world!
Hello World!
Hello World!
Hello World!
Hello World!

Deprecated: Callables of the form ["B", "parent::who"] are deprecated in script on line 41
A
Hello PHP!
]]>
   </screen>
  </example>

  &note.func-callback-exceptions;
 </sect2>

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