diff --git a/language/types/callable.xml b/language/types/callable.xml index d50923a89b6a..3d0d4e900e48 100644 --- a/language/types/callable.xml +++ b/language/types/callable.xml @@ -1,71 +1,204 @@ - Callbacks / Callables + Callables - - Callbacks can be denoted by the callable type declaration. - + + A callable is a reference to a function or method that is passed to + another function as an argument. + They are represented with the callable type declaration. + + + + +]]> + + - - Some functions like call_user_func or - usort accept user-defined callback functions as a - parameter. Callback functions can not only be simple functions, but also - object methods, including static class methods. - + + Some functions accept callback functions as a parameter, e.g. + array_map, usort, or + preg_replace_callback. + - Passing + Creation of callables + + + 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 callable type cannot be used as a type declaration for class + properties. Instead, use a Closure type declaration. + + + + Callables can be created in several different ways: + + + + + Closure object + + + &string; containing the name of a function or a method + + + + &array; containing a class name or an object + in index 0 and the method name in index 1 + + + + + &object; implementing the __invoke() + magic method + + + + + + A Closure object can be created using + anonymous function syntax, + arrow function syntax, + first-class callable + syntax, or the Closure::fromCallable method. + + + + + The first-class + callable syntax is only available as of PHP 8.1.0. + + + + + + Callback example using a <classname>Closure</classname> + + + $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); + +?> +]]> + + &example.outputs.81; + + + + - - A PHP function is passed by either its name as a string or by - a first-class callable. + + 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: array, echo, empty, eval, - exit, isset, + isset, list, print or unset. - - - - A method of an instantiated object is passed as an - array containing an object at index 0 and the - method name at index 1. Accessing protected and private methods from - within a class is allowed. - - - - Static class methods can also be passed without instantiating an - object of that class by either, passing the class name - instead of an object at index 0, or passing - 'ClassName::methodName'. - - - - Apart from common user-defined function, - anonymous functions and - arrow functions can also be - passed to a callback parameter. - + + + + Static class methods can be used without instantiating an + object 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 + ::, as in 'ClassName::methodName'. + + + + A method of an instantiated object can be a callable + when provided as an array with the object at index 0 and + the method name at index 1. + + + + The main difference between a Closure object and the + callable type is that a Closure object is + scope-independent and can always be invoked, whereas a callable type may be + scope-dependent and may not be directly invoked. + Closure is the preferred way to create callables. + + + + + While Closure 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 + Closure::fromCallable or the + first-class callable + syntax. + + + + + 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. + 'parent::method' or ["static", "method"]. + - - As of PHP 8.1.0, anonymous functions can also be created using the first class callable syntax. - + + As of PHP 8.2.0, context-dependent callables + are deprecated. Remove the context dependency by replacing + 'parent::method' with + parent::class . '::method' or use the + first-class callable + syntax. + - - Generally, any object implementing __invoke() can also - be passed to a callback parameter. - - - - - - Callback function examples - - + + + Calling various types of callables with <function>call_user_function</function> + + ]]> - - - - - - - Callback example using a <classname>Closure</classname> - - + + &example.outputs; + -]]> - - &example.outputs; - - - - - + + ¬e.func-callback-exceptions;