PHP 8.3.4 Released!

Llamadas de retorno (Callbacks / Callables)

Las llamadas de retorno, o retrollamadas, se pueden indicar con la declaración de tipo callable a partir de PHP 5.4. Esta documentación utilizó la información del tipo callback con el mismo propósito.

Algunas funciones como call_user_func() o usort() aceptan como parámetro funciones de llamada de retorno definidas por el usuario. Las funciones de llamadas de retorno no sólo pueden ser funciones simples, sino también métodos de un object, incluyendo métodos de clase estáticos.

Pasar una función de llamada de retorno

Una función de PHP se pasa por su nombre como un string. Se puede utilizar cualquier función nativa o definida por el usuario, exceptuando contrucciones del lenguaje, tales como: array(), echo, empty(), eval(), exit(), isset(), list(), print o unset().

Un método de un object instanciado se pasa como un array que contiene un object en el índice 0 y el nombre del método en el índice 1. Está permitido el acceso a métodos protegidos y privados desde dentro de una clase.

Los métodos de clase estáticos también se pueden pasar sin instanciar un object de dicha clase, pasando el nombre de la clase en lugar de un object en el índice 0. A partir de PHP 5.2.3, también es posible pasar 'NombreDeClase::nombreDeMetodo'.

A parte de las funciones comunes definidas por el usuario, las funciones anónimas también se pueden pasar a un parámetro de llamada de retorno.

Ejemplo #1 Ejemplos de funciones de llamadas de retorno

<?php

// Un ejemplo de función de llamada de retorno
function mi_función_de_llamada_de_retorno() {
echo
'¡hola mundo!';
}

// Un ejemplo de método de llamada de retorno
class MiClase {
static function
miMétodoDeLlamadaDeRetorno() {
echo
'¡Hola Mundo!';
}
}

// Tipo 1: Llamada de retorno simple
call_user_func('mi_función_de_llamada_de_retorno');

// Tipo 2: Llamada a un método de clase estático
call_user_func(array('MiClase', 'miMétodoDeLlamadaDeRetorno'));

// Tipo 3: Llamada al método de un objeto
$obj = new MiClase();
call_user_func(array($obj, 'miMétodoDeLlamadaDeRetorno'));

// Tipo 4: Llamada a un método de clase estático (A partir de PHP 5.2.3)
call_user_func('MiClase::miMétodoDeLlamadaDeRetorno');

// Tipo 5: Llamada a un método de clase estático relativo (A partir de PHP 5.3.0)
class A {
public static function
quién() {
echo
"A\n";
}
}

class
B extends A {
public static function
quién() {
echo
"B\n";
}
}

call_user_func(array('B', 'parent::quién')); // A

// Tipe 6: Los objetos que implementan __invoke se pueden emplear como retrollamadas (desde PHP 5.3)
class C {
public function
__invoke($nombre) {
echo
'Hola ', $nombre, "\n";
}
}

$c = new C();
call_user_func($c, 'PHP!');
?>

Ejemplo #2 Ejemplo de retrollamada utilizando un cierre

<?php
// Nuestro cierre
$doble = function($a) {
return
$a * 2;
};

// Este es nuestro rango de números
$números = range(1, 5);

// Usar el cierre como llamada de retorno para
// doblar el valor de cada elemento de nuestro
// rango
$números_nuevos = array_map($doble, $números);

print
implode(' ', $números_nuevos);
?>

El resultado del ejemplo sería:

2 4 6 8 10

Nota:

Las funciones de retorno de llamada que se registran con funciones como call_user_func() y call_user_func_array() no se llamarán si se produce una excepción en la función de retorno previa.

add a note

User Contributed Notes 12 notes

up
273
andrewbessa at gmail dot com
11 years ago
You can also use the $this variable to specify a callback:

<?php
class MyClass {

public
$property = 'Hello World!';

public function
MyMethod()
{
call_user_func(array($this, 'myCallbackMethod'));
}

public function
MyCallbackMethod()
{
echo
$this->property;
}

}
?>
up
192
Riikka K
8 years ago
A note on differences when calling callbacks as "variable functions" without the use of call_user_func() (e.g. "<?php $callback = 'printf'; $callback('Hello World!') ?>"):

- Using the name of a function as string has worked since at least 4.3.0
- Calling anonymous functions and invokable objects has worked since 5.3.0
- Using the array structure [$object, 'method'] has worked since 5.4.0

Note, however, that the following are not supported when calling callbacks as variable functions, even though they are supported by call_user_func():

- Calling static class methods via strings such as 'foo::doStuff'
- Calling parent method using the [$object, 'parent::method'] array structure

All of these cases are correctly recognized as callbacks by the 'callable' type hint, however. Thus, the following code will produce an error "Fatal error: Call to undefined function foo::doStuff() in /tmp/code.php on line 4":

<?php
class foo {
static function
callIt(callable $callback) {
$callback();
}

static function
doStuff() {
echo
"Hello World!";
}
}

foo::callIt('foo::doStuff');
?>

The code would work fine, if we replaced the '$callback()' with 'call_user_func($callback)' or if we used the array ['foo', 'doStuff'] as the callback instead.
up
193
computrius at gmail dot com
10 years ago
When specifying a call back in array notation (ie. array($this, "myfunc") ) the method can be private if called from inside the class, but if you call it from outside you'll get a warning:

<?php

class mc {
public function
go(array $arr) {
array_walk($arr, array($this, "walkIt"));
}

private function
walkIt($val) {
echo
$val . "<br />";
}

public function
export() {
return array(
$this, 'walkIt');
}
}

$data = array(1,2,3,4);

$m = new mc;
$m->go($data); // valid

array_walk($data, $m->export()); // will generate warning

?>

Output:
1<br />2<br />3<br />4<br />
Warning: array_walk() expects parameter 2 to be a valid callback, cannot access private method mc::walkIt() in /in/tfh7f on line 22
up
208
steve at mrclay dot org
11 years ago
Performance note: The callable type hint, like is_callable(), will trigger an autoload of the class if the value looks like a static method callback.
up
191
edanschwartz at gmail dot com
9 years ago
You can use 'self::methodName' as a callable, but this is dangerous. Consider this example:

<?php
class Foo {
public static function
doAwesomeThings() {
FunctionCaller::callIt('self::someAwesomeMethod');
}

public static function
someAwesomeMethod() {
// fantastic code goes here.
}
}

class
FunctionCaller {
public static function
callIt(callable $func) {
call_user_func($func);
}
}

Foo::doAwesomeThings();
?>

This results in an error:
Warning: class 'FunctionCaller' does not have a method 'someAwesomeMethod'.

For this reason you should always use the full class name:
<?php
FunctionCaller
::callIt('Foo::someAwesomeMethod');
?>

I believe this is because there is no way for FunctionCaller to know that the string 'self' at one point referred to to `Foo`.
up
175
metamarkers at gmail dot com
10 years ago
you can pass an object as a callable if its class defines the __invoke() magic method..
up
114
mariano dot REMOVE dot perez dot rodriguez at gmail dot com
8 years ago
I needed a function that would determine the type of callable being passed, and, eventually,
normalized it to some extent. Here's what I came up with:

<?php

/**
* The callable types and normalizations are given in the table below:
*
* Callable | Normalization | Type
* ---------------------------------+---------------------------------+--------------
* function (...) use (...) {...} | function (...) use (...) {...} | 'closure'
* $object | $object | 'invocable'
* "function" | "function" | 'function'
* "class::method" | ["class", "method"] | 'static'
* ["class", "parent::method"] | ["parent of class", "method"] | 'static'
* ["class", "self::method"] | ["class", "method"] | 'static'
* ["class", "method"] | ["class", "method"] | 'static'
* [$object, "parent::method"] | [$object, "parent::method"] | 'object'
* [$object, "self::method"] | [$object, "method"] | 'object'
* [$object, "method"] | [$object, "method"] | 'object'
* ---------------------------------+---------------------------------+--------------
* other callable | idem | 'unknown'
* ---------------------------------+---------------------------------+--------------
* not a callable | null | false
*
* If the "strict" parameter is set to true, additional checks are
* performed, in particular:
* - when a callable string of the form "class::method" or a callable array
* of the form ["class", "method"] is given, the method must be a static one,
* - when a callable array of the form [$object, "method"] is given, the
* method must be a non-static one.
*
*/
function callableType($callable, $strict = true, callable& $norm = null) {
if (!
is_callable($callable)) {
switch (
true) {
case
is_object($callable):
$norm = $callable;
return
'Closure' === get_class($callable) ? 'closure' : 'invocable';
case
is_string($callable):
$m = null;
if (
preg_match('~^(?<class>[a-z_][a-z0-9_]*)::(?<method>[a-z_][a-z0-9_]*)$~i', $callable, $m)) {
list(
$left, $right) = [$m['class'], $m['method']];
if (!
$strict || (new \ReflectionMethod($left, $right))->isStatic()) {
$norm = [$left, $right];
return
'static';
}
} else {
$norm = $callable;
return
'function';
}
break;
case
is_array($callable):
$m = null;
if (
preg_match('~^(:?(?<reference>self|parent)::)?(?<method>[a-z_][a-z0-9_]*)$~i', $callable[1], $m)) {
if (
is_string($callable[0])) {
if (
'parent' === strtolower($m['reference'])) {
list(
$left, $right) = [get_parent_class($callable[0]), $m['method']];
} else {
list(
$left, $right) = [$callable[0], $m['method']];
}
if (!
$strict || (new \ReflectionMethod($left, $right))->isStatic()) {
$norm = [$left, $right];
return
'static';
}
} else {
if (
'self' === strtolower($m['reference'])) {
list(
$left, $right) = [$callable[0], $m['method']];
} else {
list(
$left, $right) = $callable;
}
if (!
$strict || !(new \ReflectionMethod($left, $right))->isStatic()) {
$norm = [$left, $right];
return
'object';
}
}
}
break;
}
$norm = $callable;
return
'unknown';
}
$norm = null;
return
false;
}

?>

Hope someone else finds it useful.
up
10
InvisibleSmiley
2 years ago
If you pass a callable method to a function with a callable type declaration, the error message is misleading:

<?php
class X {
protected function
foo(): void {}
}

function
bar(callable $c) {}

$x = new X;
$c = [$x, 'foo'];
bar($c);
?>

Error message will be something like "Argument #1 ($c) must be of type callable, array given" while the actual problem here is only the visibility of method "foo". All you need to do is changing it to public (or use a different approach, e.g. with a Closure).
up
9
gulaschsuppe2 at gmail dot com
4 years ago
I tried many possible ways of calling functions by function name directly and assigned to a variable on 3v4l. Not mentioned yet, it is possible to use an array as a caller, at least since PHP 7.1.25. The following script contains all the information I gained:

<?php

// Call function via function name:
// Basics:
// A function can also be called by using its string name:
function callbackFunc() {
echo
'Hello World';
}

'callbackFunc'(); // Hello World

// A function can also be called if its name is assigned to a variable:
function callbackFunc() {
echo
'Hello World';
}

$funcName = 'callbackFunc';
$funcName(); // Hello World

// Static class method:
// It is also possible to call a public static class method via 'ClassName::functioName' notation:
class A {
public static function
callbackMethod() {
echo
"Hello World\n";
}
}
'A::callbackMethod'(); // Hello World

$funcName = 'A::callbackMethod';
$funcName(); // Hello World

// Non static class method:
// It is also possible to call non static class methods by creating an array which first element is the object the method should be called on and the second element is the non static method to be called. The array can directly be used as a caller:
class A {
private
$prop = "Hello World\n";

public function
callbackMethod() {
echo
$this->prop;
}
}

$a = new A;
[
$a, 'callbackMethod']();
$funcCallArr = [$a, 'callbackMethod'];
$funcCallArr();

// Of course this also works inside the class with '$this':
class A {
private function
privCallback() {
echo
'Private';
}

public function
privCallbackCaller($funcName) {
[
$this, $funcName]();
}
}

(new
A)->privCallbackCaller('privCallback'); // Private

?>
up
24
bradyn at NOSPAM dot bradynpoulsen dot com
7 years ago
When trying to make a callable from a function name located in a namespace, you MUST give the fully qualified function name (regardless of the current namespace or use statements).

<?php

namespace MyNamespace;

function
doSomethingFancy($arg1)
{
// do something...
}

$values = [1, 2, 3];

array_map('doSomethingFancy', $values);
// array_map() expects parameter 1 to be a valid callback, function 'doSomethingFancy' not found or invalid function name

array_map('MyNamespace\doSomethingFancy', $values);
// => [..., ..., ...]
up
4
pawel dot tadeusz dot niedzielski at gmail dot com
7 years ago
@edanschwartz at gmail dot com

You can use ::class property to always indicate the class you're in when using static methods:

<?php
class Foo {
public static function
doAwesomeThings() {
FunctionCaller::callIt(self::class . '::someAwesomeMethod');
}

public static function
someAwesomeMethod() {
// fantastic code goes here.
}
}

class
FunctionCaller {
public static function
callIt(callable $func) {
call_user_func($func);
}
}

Foo::doAwesomeThings();
?>
up
2
chris dot rutledge at gmail dot com
5 years ago
Having read this line in the manual above,

"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."

I decided to do some testing to see if I could access private methods using the call_user_func methods. Thankfully not, but for completeness here is my test which also covers using static and object contexts

<?php
class foo {

public static
$isInstance = false;

public function
__construct() {
self::$isInstance = true;
}

public function
bar() {
var_dump(self::$isInstance);
echo
__METHOD__;
}

private function
baz() {
var_dump(self::$isInstance);
echo
__METHOD__;
}

public function
qux() {
$this->baz();
}

public function
quux() {
self::baz();
}
}

call_user_func(['foo','bar']); //fase, foo:bar

call_user_func(['foo','baz']); //warning, cannot access private method

call_user_func(['foo','quux']); //false, foo::baz

call_user_func(['foo','qux']); //fatal, Using $this when not in object context

$foo = new foo;

call_user_func([$foo,'bar']); //true, foo::bar
call_user_func([$foo,'baz']); //warning, cannot access private method
call_user_func([$foo,'qux']); //true, foo::baz

call_user_func(['foo','bar']); //true, foo::bar (static call, yet $isInstance is true)

?>
To Top