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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<sect1 xml:id="language.types.callable">
 <title>Callables</title>

 <simpara>
  A callable is a reference to a function or method that is passed to
  another function as an argument.
  They are represented with the <type>callable</type> type declaration.
 </simpara>
 <informalexample>
  <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
function foo(callable $callback) {
    $callback();
}
?>
]]>
  </programlisting>
 </informalexample>

 <simpara>
  Some functions accept callback functions as a parameter, e.g.
  <function>array_map</function>, <function>usort</function>, or
  <function>preg_replace_callback</function>.
 </simpara>

 <sect2 xml:id="language.types.callable.passing">
  <title>Creation of callables</title>

  <simpara>
   A callable is a type that represents something that can be invoked.
   Callables can be passed as arguments to functions or methods which
   expect a callback parameter or they can be invoked directly.
   The <type>callable</type> type cannot be used as a type declaration for class
   properties. Instead, use a <classname>Closure</classname> type declaration.
  </simpara>

  <simpara>
   Callables can be created in several different ways:
  </simpara>

  <itemizedlist>
   <listitem>
    <simpara><classname>Closure</classname> object</simpara>
   </listitem>
   <listitem>
    <simpara>&string; containing the name of a function or a method</simpara>
   </listitem>
   <listitem>
    <simpara>
     &array; containing a class name or an <type>object</type>
     in index 0 and the method name in index 1
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     &object; implementing the <link linkend="object.invoke">__invoke()</link>
     magic method
    </simpara>
   </listitem>
  </itemizedlist>

  <simpara>
   A <classname>Closure</classname> object can be created using
   <link linkend="functions.anonymous">anonymous function</link> syntax,
   <link linkend="functions.arrow">arrow function</link> syntax,
   <link linkend="functions.first_class_callable_syntax">first-class callable
   syntax</link>, or the <methodname>Closure::fromCallable</methodname> method.
  </simpara>

  <note>
   <simpara>
    The <link linkend="functions.first_class_callable_syntax">first-class
    callable syntax</link> is only available as of PHP 8.1.0.
   </simpara>
  </note>

  <example>
   <title>
    Callback example using a <classname>Closure</classname>
   </title>
   <programlisting role="php">
<![CDATA[
<?php
// Using anonymous function syntax
$double1 = function ($a) {
    return $a * 2;
};

// Using first-class callable syntax
function double_function($a) {
    return $a * 2;
}
$double2 = double_function(...);

// Using arrow function syntax
$double3 = fn($a) => $a * 2;

// Using Closure::fromCallable
$double4 = Closure::fromCallable('double_function');

// Use the closure as a callback here to
// double the size of each element in our 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>
   A callable can also be a string containing the name of a function or
   a static method.
   Any built-in or user-defined function can be used, except language constructs
   such as: <function>array</function>, <function>echo</function>,
   <function>empty</function>, <function>eval</function>,
   <function>isset</function>,
   <function>list</function>, <function>print</function> or
   <function>unset</function>.
  </simpara>

  <simpara>
   Static class methods can be used without instantiating an
   <type>object</type> of that class by either, creating an array with
   the class name at index 0 and the method name at index 1, or by using
   the special syntax with the scope resolution operator
   <literal>::</literal>, as in <literal>'ClassName::methodName'</literal>.
  </simpara>

  <simpara>
   A method of an instantiated <type>object</type> can be a callable
   when provided as an array with the <type>object</type> at index 0 and
   the method name at index 1.
  </simpara>

  <simpara>
   The main difference between a <classname>Closure</classname> object and the
   <type>callable</type> type is that a <classname>Closure</classname> object is
   scope-independent and can always be invoked, whereas a callable type may be
   scope-dependent and may not be directly invoked.
   <classname>Closure</classname> is the preferred way to create callables.
  </simpara>

  <note>
   <simpara>
    While <classname>Closure</classname> objects are bound to the scope
    where they are created, callables referencing class methods as strings
    or arrays are resolved in the scope where they are called.
    To create a callable from a private or protected method, which can then be
    invoked from outside the class scope, use
    <methodname>Closure::fromCallable</methodname> or the
    <link linkend="functions.first_class_callable_syntax">first-class callable
    syntax</link>.
   </simpara>
  </note>

  <simpara>
   PHP allows the creation of callables which can be used as a callback argument
   but cannot be called directly.
   These are context-dependent callables which reference a class method in the
   inheritance hierarchy of a class, e.g.
   <literal>'parent::method'</literal> or <literal>["static", "method"]</literal>.
  </simpara>

  <note>
   <simpara>
    As of PHP 8.2.0, context-dependent callables
    are deprecated. Remove the context dependency by replacing
    <literal>'parent::method'</literal> with
    <literal>parent::class . '::method'</literal> or use the
    <link linkend="functions.first_class_callable_syntax">first-class callable
    syntax</link>.
   </simpara>
  </note>

  <example>
   <title>
    Calling various types of callables with <function>call_user_function</function>
   </title>
   <programlisting role="php">
<![CDATA[
<?php

// An example callback function
function my_callback_function() {
    echo 'hello world!', PHP_EOL;
}

// An example callback method
class MyClass {
    static function myCallbackMethod() {
        echo 'Hello World!', PHP_EOL;
    }
}

// Type 1: Simple callback
call_user_func('my_callback_function');

// Type 2: Static class method call
call_user_func(['MyClass', 'myCallbackMethod']);

// Type 3: Object method call
$obj = new MyClass();
call_user_func([$obj, 'myCallbackMethod']);

// Type 4: Static class method call
call_user_func('MyClass::myCallbackMethod');

// Type 5: Static class method call using ::class keyword
call_user_func([MyClass::class, 'myCallbackMethod']);

// Type 6: Relative static class method call
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: Objects implementing __invoke can be used as 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
-->