PHP Callables de Primeira Classe

Muitas funções do PHP recebem outra função como argumento: array_map aplica uma função a cada item, usort usa uma função para comparar, array_filter usa uma para decidir quem fica. Algo que pode ser chamado como função é um callable ("chamável"). O PHP tem várias formas de escrever um callable; a mais moderna, do PHP 8.1, é a mais curta e a mais segura: strlen(...).

Antes, veja Funções Anônimas e Arrow Functions: lá você criou funções novas para passar adiante (fn($x) => $x * 2). Aqui o assunto é passar funções e métodos que já existem.

A ideia: passar a receita, não o bolo

Quando a Ana pede ao Bruno "faça um bolo", o Bruno entrega o bolo pronto. Mas, se ela pede "use esta receita em cada um destes 10 ingredientes", ela entrega a receita, e o Bruno a aplica quantas vezes precisar.

Em PHP, strlen("caneca") é o bolo: a função roda e devolve 6. Para o array_map, a Ana precisa entregar a receita, a própria função strlen, sem rodá-la. A dúvida é: como escrever "a função strlen" sem chamá-la? É isso que esta aula responde.

As formas antigas: texto e array

Durante muitos anos, o PHP aceitou como callable um texto com o nome da função, ou um array com o objeto e o nome do método:

<?php
class Loja
{
    public function __construct(private float $taxa) {}

    public function comTaxa(float $preco): float
    {
        return round($preco * (1 + $this->taxa), 2);
    }

    public static function formatar(float $valor): string
    {
        return "R$ " . number_format($valor, 2, ",", ".");
    }
}

$precos = [10, 19.9, 49.9];
$loja = new Loja(0.1);

// 1. string com o nome de uma função
print_r(array_map('round', $precos));

// 2. array [objeto, 'método']
print_r(array_map([$loja, 'comTaxa'], $precos));

// 3. array ['Classe', 'método estático'] ou string 'Classe::método'
print_r(array_map(['Loja', 'formatar'], $precos));
print_r(array_map('Loja::formatar', $precos));

// chamando direto a partir de uma variável
$f = 'strtoupper';
echo $f("caneca"), "\n";
$g = [$loja, 'comTaxa'];
echo $g(100), "\n";
echo call_user_func('str_repeat', "ab", 3), "\n";

$ php antigo.php
Array
(
    [0] => 10
    [1] => 20
    [2] => 50
)
Array
(
    [0] => 11
    [1] => 21.89
    [2] => 54.89
)
Array
(
    [0] => R$ 10,00
    [1] => R$ 19,90
    [2] => R$ 49,90
)
Array
(
    [0] => R$ 10,00
    [1] => R$ 19,90
    [2] => R$ 49,90
)
CANECA
110
ababab

Funciona, e você vai ver muito isso em código existente. Mas tem três problemas.

Problema 1: o erro aparece tarde e longe

Para o PHP, 'strlenn' é só um texto. Ninguém confere se a função existe até o array_map tentar usá-la:

<?php
$nomes = ["Ana", "Bruno", "Carla"];
print_r(array_map('strlenn', $nomes));

$ php typo.php

Fatal error: Uncaught TypeError: array_map(): Argument #1 ($callback) must be a valid callback or null, function "strlenn" not found or invalid function name in /home/ana/call/typo.php:3
Stack trace:
#0 /home/ana/call/typo.php(3): array_map('strlenn', Array)
#1 {main}
  thrown in /home/ana/call/typo.php on line 3

Aqui o erro ficou perto, mas, se o texto tivesse sido guardado numa variável no começo do programa e usado bem depois, o erro apontaria para a linha do uso.

Problema 2: os editores não enxergam

Para o editor (veja Editores e IDEs), 'comTaxa' é um texto qualquer. Se você usar "Renomear método" para trocar comTaxa por aplicarTaxa, o texto não muda e o programa quebra. "Ir para a definição" e "Encontrar usos" também não funcionam.

Problema 3: a visibilidade depende de onde se chama

O array [$this, 'capitalizar'] com um método private funciona dentro da classe, mas o mesmo array, usado de fora, é recusado:

$ php privado.php
…
Fatal error: Uncaught TypeError: array_map(): Argument #1 ($callback) must be a valid callback or null, cannot access private method Carrinho::capitalizar() in /home/ana/call/privado.php:31
…

(O arquivo completo está mais abaixo, na seção de métodos privados.)

is_callable e o tipo callable

Para saber se um valor pode ser chamado, existe is_callable():

<?php
class Loja
{
    public function publico() {}
    private function privado() {}
}
$loja = new Loja();
var_dump(is_callable('strlen'));
var_dump(is_callable('strlenn'));
var_dump(is_callable([$loja, 'publico']));
var_dump(is_callable([$loja, 'privado']));
var_dump(is_callable(fn() => 1));

$ php iscall.php
bool(true)
bool(false)          « a função não existe
bool(true)
bool(false)          « existe, mas é privada (vista de fora)
bool(true)           « funções anônimas também são callables

E, para exigir um callable num parâmetro, use o tipo callable:

<?php
function aplicarATodos(array $itens, callable $acao): array
{
    $resultado = [];
    foreach ($itens as $item) {
        $resultado[] = $acao($item);
    }
    return $resultado;
}

print_r(aplicarATodos(["ana", "bruno"], ucfirst(...)));
print_r(aplicarATodos(["ana", "bruno"], 'strtoupper'));
print_r(aplicarATodos(["ana", "bruno"], fn($n) => "Olá, $n"));
print_r(aplicarATodos(["ana"], "nao_existe"));

$ php aplicar.php
Array
(
    [0] => Ana
    [1] => Bruno
)
Array
(
    [0] => ANA
    [1] => BRUNO
)
Array
(
    [0] => Olá, ana
    [1] => Olá, bruno
)

Fatal error: Uncaught TypeError: aplicarATodos(): Argument #2 ($acao) must be of type callable, string given, called in /home/ana/call/aplicar.php on line 14 and defined in /home/ana/call/aplicar.php:2
Stack trace:
#0 /home/ana/call/aplicar.php(14): aplicarATodos(Array, 'nao_existe')
#1 {main}
  thrown in /home/ana/call/aplicar.php on line 2

As três formas foram aceitas; o texto "nao_existe", não. (O ucfirst(...) da primeira chamada é a forma nova, explicada daqui a pouco.) O tipo callable só pode ser usado em parâmetros e retornos, não em propriedades de classe; para guardar numa propriedade, use o tipo Closure.

Closure::fromCallable()

O PHP 7.1 trouxe um meio-termo: transformar qualquer callable num objeto Closure (o mesmo tipo das funções anônimas). A conferência acontece na hora da conversão:

<?php
class Loja
{
    public function __construct(private float $taxa) {}
    public function comTaxa(float $preco): float { return round($preco * (1 + $this->taxa), 2); }
}
$tamanho = Closure::fromCallable('strlen');
$taxa = Closure::fromCallable([new Loja(0.1), 'comTaxa']);
var_dump($tamanho);
echo $tamanho("caneca"), "\n";
echo $taxa(100), "\n";

$ php fromcallable.php
object(Closure)#1 (2) {
  ["function"]=>
  string(6) "strlen"
  ["parameter"]=>
  array(1) {
    ["$string"]=>
    string(10) "<required>"
  }
}
6
110

O var_dump mostra o que há dentro do Closure: qual função ele embrulha (strlen) e os parâmetros dela ($string, obrigatório). Ainda assim, o nome continua sendo um texto ('strlen'), com os problemas 1 e 2. A forma nova resolve isso.

Callable de primeira classe: strlen(...) PHP 8.1+

A ideia é simples: escreva a chamada normalmente, mas, no lugar dos argumentos, coloque três pontos. O resultado não é a chamada: é um Closure que fará a chamada depois.

<?php
class Loja
{
    public function __construct(private float $taxa) {}

    public function comTaxa(float $preco): float
    {
        return round($preco * (1 + $this->taxa), 2);
    }

    public static function formatar(float $valor): string
    {
        return "R$ " . number_format($valor, 2, ",", ".");
    }
}

$loja = new Loja(0.1);

$tamanho  = strlen(...);
$comTaxa  = $loja->comTaxa(...);
$formatar = Loja::formatar(...);

var_dump($tamanho);
echo $tamanho("caneca"), "\n";
echo $comTaxa(100), "\n";
echo $formatar(1234.5), "\n";

$precos = [10, 19.9, 49.9];
print_r(array_map($formatar, array_map($comTaxa, $precos)));

strlen(...)

"A função strlen, ainda não chamada." Os ... aqui não são o operador de funções variádicas; dentro dos parênteses, sozinhos, querem dizer "os argumentos virão depois".

$loja->comTaxa(...)

"O método comTaxa deste objeto". O objeto fica guardado dentro do Closure.

Loja::formatar(...)

"O método estático formatar da classe Loja".

$tamanho("caneca")

Chama de fato, como qualquer função.

$ php primeira.php
object(Closure)#2 (2) {
  ["function"]=>
  string(6) "strlen"
  ["parameter"]=>
  array(1) {
    ["$string"]=>
    string(10) "<required>"
  }
}
6
110
R$ 1.234,50
Array
(
    [0] => R$ 11,00
    [1] => R$ 21,89
    [2] => R$ 54,89
)

O resultado é exatamente o mesmo Closure do Closure::fromCallable('strlen'), mas escrito como código, não como texto. Por isso:

• O erro aparece na hora e no lugar certo. Com o nome errado:

$ php typo2.php          « $tamanho = strlenn(...);

Fatal error: Uncaught Error: Call to undefined function strlenn() in /home/ana/call/typo2.php:3
Stack trace:
#0 {main}
  thrown in /home/ana/call/typo2.php on line 3

• O editor entende: renomear, "ir para a definição" e autocompletar funcionam.
• A visibilidade é a de onde o callable foi criado (próxima seção).

<?php
class Loja
{
    public function __construct(private float $taxa) {}

    public function comTaxa(float $preco): float
    {
        return round($preco * (1 + $this->taxa), 2);
    }

    public static function formatar(float $valor): string
    {
        return "R$ " . number_format($valor, 2, ",", ".");
    }
}

$loja = new Loja(0.1);

$maiuscula = 'strtoupper';
$taxa = [$loja, 'comTaxa'];
$formatar = 'Loja::formatar';

echo $maiuscula("caneca"), "\n";
echo $formatar($taxa(1122.27)), "\n";

<?php
class Loja
{
    public function __construct(private float $taxa) {}

    public function comTaxa(float $preco): float
    {
        return round($preco * (1 + $this->taxa), 2);
    }

    public static function formatar(float $valor): string
    {
        return "R$ " . number_format($valor, 2, ",", ".");
    }
}

$loja = new Loja(0.1);

$maiuscula = strtoupper(...);
$taxa = $loja->comTaxa(...);
$formatar = Loja::formatar(...);

echo $maiuscula("caneca"), "\n";
echo $formatar($taxa(1122.27)), "\n";

Métodos privados como callable

Dentro de uma classe, $this->metodo(...) cria um Closure que "lembra" que foi criado lá dentro. Ele pode ser entregue para fora e continua funcionando, mesmo com um método private:

<?php
class Carrinho
{
    private array $itens = ["caneca", "camiseta", "boné"];

    private function capitalizar(string $s): string
    {
        return ucfirst($s);
    }

    public function nomes(): array
    {
        return array_map($this->capitalizar(...), $this->itens);
    }

    public function nomesAntigo(): array
    {
        return array_map([$this, 'capitalizar'], $this->itens);
    }

    public function entregarCallable(): Closure
    {
        return $this->capitalizar(...);
    }
}
$c = new Carrinho();
print_r($c->nomes());
print_r($c->nomesAntigo());
$f = $c->entregarCallable();
echo $f("bolsa"), "\n";
print_r(array_map([$c, 'capitalizar'], ["x"]));

$ php privado.php
Array
(
    [0] => Caneca
    [1] => Camiseta
    [2] => Boné
)
Array
(
    [0] => Caneca
    [1] => Camiseta
    [2] => Boné
)
Bolsa                « o Closure criado lá dentro funciona aqui fora

Fatal error: Uncaught TypeError: array_map(): Argument #1 ($callback) must be a valid callback or null, cannot access private method Carrinho::capitalizar() in /home/ana/call/privado.php:31
Stack trace:
#0 /home/ana/call/privado.php(31): array_map(Array, Array)
#1 {main}
  thrown in /home/ana/call/privado.php on line 31

A classe decide o que entrega: o Closure é uma "chave" que ela mesma deu. Já o array [$c, 'capitalizar'], montado de fora, é recusado, porque quem tenta usá-lo (o array_map, chamado de fora da classe) não tem acesso. Veja Visibilidade.

Na prática: array_map, array_filter, usort

A Ana recebeu uma lista de produtos digitada às pressas, com espaços sobrando, maiúsculas misturadas e itens vazios. Com funções que já existem no PHP, ela limpa tudo sem escrever nenhuma função nova:

<?php
$entrada = ["  caneca ", "CAMISETA", " boné", "12", "", "chaveiro  "];

$limpos = array_map(trim(...), $entrada);
$semVazios = array_filter($limpos, strlen(...));
$minusculos = array_map(mb_strtolower(...), $semVazios);
usort($minusculos, strcmp(...));

print_r($minusculos);
echo implode(", ", array_map(ucfirst(...), $minusculos)), "\n";

$ php uso.php
Array
(
    [0] => 12
    [1] => boné
    [2] => camiseta
    [3] => caneca
    [4] => chaveiro
)
12, Boné, Camiseta, Caneca, Chaveiro

O "12" ficou em primeiro porque, na comparação de textos do strcmp, dígitos vêm antes das letras. Repare também que array_map(ucfirst(...), …) cabe numa linha, enquanto a versão com função anônima seria array_map(fn($s) => ucfirst($s), …). Quando a função já existe e recebe exatamente um argumento, o callable de primeira classe é a escrita mais limpa. Na próxima aula, o operador pipe |> usa essa mesma sintaxe para encadear transformações da esquerda para a direita.

Todas as formas: qual usar

Quando dá errado

$ php nullsafe.php       « $f = $loja?->comTaxa(...);

Fatal error: Cannot combine nullsafe operator with Closure creation in /home/ana/call/nullsafe.php on line 3
Stack trace:
#0 {main}

$ php novo.php           « $f = new DateTime(...);

Fatal error: Cannot create Closure for new expression in /home/ana/call/novo.php on line 2
Stack trace:
#0 {main}

Referência

Exercícios

<?php
$alunos = ["  carla DIAS ", "", "ANA souza", "   ", " bruno lima"];

// seu código aqui

echo implode(", ", $alunos), "\n";

<?php
$alunos = ["  carla DIAS ", "", "ANA souza", "   ", " bruno lima"];

$alunos = array_map(trim(...), $alunos);
$alunos = array_filter($alunos, strlen(...));
$alunos = array_map(mb_strtolower(...), $alunos);
$alunos = array_map(ucwords(...), $alunos);
sort($alunos);

echo implode(", ", $alunos), "\n";

Resumo

• Callable = algo que pode ser chamado: função, método, função anônima. Serve para passar uma "receita" a array_map, array_filter, usort…
• Formas antigas: 'strlen', [$obj, 'metodo'], 'Classe::metodo'. Funcionam, mas o erro aparece tarde e o editor não as entende.
• PHP 8.1+ strlen(...), $obj->metodo(...), Classe::metodo(...) criam um Closure: conferido na hora, visível para o editor, com a visibilidade de onde foi criado.
• is_callable() testa; callable é o tipo de parâmetro; Closure, o de propriedade.
• Função já pronta, com um argumento: (...). Precisa fixar argumentos ou combinar: arrow function.