Funções em PHP: definir, retorno, parâmetros e tipos

Uma função PHP é definida com a palavra-chave function, um nome, uma lista de parâmetros e um corpo; return devolve um valor a quem chamou. function add(int $a, int $b): int { return $a + $b; } a define, e add(2, 3) a chama e retorna 5.

<?php
function greet(string $name): string
{
    return "Hello, $name";
}

function add(int $a, int $b): int
{
    return $a + $b;
}

echo greet('Ada'), "\n";
echo add(2, 3), "\n";
echo add(add(1, 2), 10), "\n";

Os string e int antes dos parâmetros são declarações de tipo, e : string depois dos parênteses é o tipo de retorno. Os dois são opcionais, mas pegam erros cedo e documentam o que a função espera.

Valores de retorno e retornar vários valores

return encerra a função na hora. Uma função sem return, ou com um return; sozinho, retorna null; declare : void quando ela é chamada só pelo efeito. Uma função retorna um valor, mas esse valor pode ser um array, que você desestrutura do lado de quem chama:

<?php
function grade(int $score): string
{
    if ($score >= 90) {
        return 'A';
    }
    return $score >= 75 ? 'B' : 'C';   // reached only below 90
}

function stats(array $numbers): array
{
    return [
        'min' => min($numbers),
        'max' => max($numbers),
        'avg' => array_sum($numbers) / count($numbers),
    ];
}

function logLine(string $msg): void
{
    echo "[log] $msg\n";
}

echo grade(95), grade(80), grade(40), "\n";

['min' => $min, 'max' => $max, 'avg' => $avg] = stats([4, 8, 15, 16, 23, 42]);
echo "min $min, max $max, average $avg\n";

[$quotient, $remainder] = [intdiv(17, 5), 17 % 5];
echo "17 / 5 = $quotient remainder $remainder\n";

var_dump(logLine('saved'));   // a void function returns null

Veja desestruturação de arrays para as outras formas de [...] =.

Parâmetros padrão e argumentos nomeados

Um parâmetro com = value é opcional: quem chama pode omiti-lo. Parâmetros opcionais vêm depois dos obrigatórios. Desde o PHP 8.0, argumentos nomeados deixam quem chama passar qualquer parâmetro pelo nome, então você pode pular os opcionais de que não precisa.

<?php
function makeTag(string $text, string $tag = 'p', ?string $class = null, bool $escape = true): string
{
    $body = $escape ? htmlspecialchars($text) : $text;
    $attr = $class !== null ? " class=\"$class\"" : '';
    return "<$tag$attr>$body</$tag>";
}

echo makeTag('Hello'), "\n";
echo makeTag('Title', 'h1'), "\n";

// Named arguments: skip $tag and $class, set only $escape
echo makeTag('<b>bold</b>', escape: false), "\n";
echo makeTag(class: 'note', text: 'Order does not matter'), "\n";

Argumentos nomeados também deixam legíveis as chamadas a funções nativas: str_pad('7', 3, '0', pad_type: STR_PAD_LEFT). O nome do parâmetro passa a fazer parte da interface pública da função, então renomear um parâmetro pode quebrar quem usa os nomes.

Passagem por referência

Normalmente o PHP passa uma cópia de cada argumento, então a função não pode alterar a variável de quem chamou. Um & antes de um parâmetro passa a própria variável. Funções nativas como sort() funcionam assim.

<?php
function addOne(int $n): void
{
    $n++;          // changes the copy only
}

function addOneRef(int &$n): void
{
    $n++;          // changes the caller's variable
}

$a = 5;
addOne($a);
echo $a, "\n";

addOneRef($a);
echo $a, "\n";

function addItem(array &$cart, string $item): void
{
    $cart[] = $item;
}

$cart = [];
addItem($cart, 'apple');
addItem($cart, 'pear');
print_r($cart);

Retornar um novo valor costuma ser mais claro que alterar um argumento. Use referências quando a função realmente deve modificar algo no lugar.

Declarações de tipo e strict_types

Por padrão, o PHP converte os argumentos para o tipo declarado quando consegue: add("5", 3) transforma "5" em 5. Colocar declare(strict_types=1); bem no topo do arquivo desliga isso para as chamadas feitas naquele arquivo, então um tipo errado lança um TypeError em vez de ser convertido.

<?php
declare(strict_types=1);
// This throws a TypeError on purpose: "5" is a string, not an int

function add(int $a, int $b): int
{
    return $a + $b;
}

echo add(2, 3), "\n";
echo add("5", 3), "\n";

Sem a linha do declare, a mesma chamada imprime 8. Strings que não são números, como "five", lançam um TypeError nos dois modos.

Os tipos que você pode declarar para parâmetros e valores de retorno:

<?php
// ?string: a string or null
function findUser(int $id): ?string
{
    $users = [1 => 'Ada', 2 => 'Linus'];
    return $users[$id] ?? null;
}

// int|float: a union type (PHP 8.0)
function half(int|float $n): float
{
    return $n / 2;
}

// mixed: anything at all
function describe(mixed $value): string
{
    return get_debug_type($value);
}

var_dump(findUser(1), findUser(9));
var_dump(half(5), half(2.5));
echo describe([1, 2]), ' ', describe(null), ' ', describe(1.5), "\n";

never é um tipo de retorno para funções que sempre lançam exceção ou encerram o script. Nomes de classes e interfaces também funcionam como tipos.

Número variável de argumentos com ...$args

...$numbers reúne qualquer quantidade de argumentos num array. O mesmo ... do lado de quem chama espalha um array em argumentos separados.

<?php
function sum(int ...$numbers): int
{
    return array_sum($numbers);
}

echo sum(), "\n";
echo sum(1, 2, 3), "\n";

$values = [10, 20, 30];
echo sum(...$values), "\n";          // spread an array

function logMessage(string $level, string ...$parts): string
{
    return strtoupper($level) . ': ' . implode(' ', $parts);
}

echo logMessage('info', 'user', 'Ada', 'logged in'), "\n";

Usar uma variável de fora dentro de uma função

Uma função tem o próprio escopo. Uma variável definida fora dela não é visível dentro, o que surpreende quem vem do JavaScript:

<?php
$taxRate = 0.2;

function priceWithTax(float $price): float
{
    return $price * (1 + $taxRate);   // $taxRate is undefined here
}

Warning: Undefined variable $taxRate in /path/to/index.php on line 6

e a função retorna o preço sem imposto. Passe o valor como parâmetro. Isso deixa a função honesta sobre aquilo de que depende e fácil de testar:

<?php
$taxRate = 0.2;

function priceWithTax(float $price, float $taxRate): float
{
    return $price * (1 + $taxRate);
}

echo priceWithTax(100, $taxRate), "\n";
echo priceWithTax(100, 0.1), "\n";

A palavra-chave global também funciona, mas esconde a dependência; o escopo de variáveis a explica. Para funções curtas passadas a outras funções, como callbacks para o array_map(), veja funções anônimas, que podem capturar variáveis de fora com use.