Funciones en PHP: definir, return, parámetros y tipos

Una función de PHP se define con la palabra clave function, un nombre, una lista de parámetros y un cuerpo; return devuelve un valor a quien la llama. function add(int $a, int $b): int { return $a + $b; } la define, y add(2, 3) la llama y devuelve 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";

Los string e int delante de los parámetros son declaraciones de tipo, y : string después de los paréntesis es el tipo de retorno. Los dos son opcionales, pero detectan errores pronto y documentan lo que espera la función.

Valores de retorno y devolver varios valores

return termina la función inmediatamente. Una función sin return, o con un simple return;, devuelve null; declara : void cuando solo se llama por su efecto. Una función devuelve un valor, pero ese valor puede ser un array, que desestructuras en el lado de quien llama:

<?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

Consulta la desestructuración de arrays para las demás formas de [...] =.

Parámetros por defecto y argumentos con nombre

Un parámetro con = value es opcional: quien llama puede omitirlo. Los parámetros opcionales van después de los obligatorios. Desde PHP 8.0, los argumentos con nombre permiten a quien llama pasar cualquier parámetro por su nombre, así que puedes saltarte los opcionales que no necesitas.

<?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";

Los argumentos con nombre también hacen legibles las llamadas a funciones nativas: str_pad('7', 3, '0', pad_type: STR_PAD_LEFT). El nombre del parámetro pasa a formar parte de la interfaz pública de la función, así que renombrar un parámetro puede romper a quien lo llama usando nombres.

Paso por referencia

Normalmente PHP pasa una copia de cada argumento, así que la función no puede cambiar la variable de quien la llama. Un & delante de un parámetro pasa la propia variable. Las funciones nativas como sort() funcionan así.

<?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);

Devolver un valor nuevo suele ser más claro que cambiar un argumento. Usa referencias cuando la función realmente esté pensada para modificar algo en el sitio.

Declaraciones de tipo y strict_types

Por defecto, PHP convierte los argumentos al tipo declarado cuando puede: add("5", 3) convierte "5" en 5. Poner declare(strict_types=1); al principio del archivo lo desactiva para las llamadas hechas en ese archivo, así que un tipo incorrecto lanza un TypeError en lugar de convertirse.

<?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";

Sin la línea declare, la misma llamada imprime 8. Las cadenas que no son números, como "five", lanzan un TypeError en los dos modos.

Los tipos que puedes declarar para parámetros y 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 es un tipo de retorno para funciones que siempre lanzan una excepción o terminan el script. Los nombres de clases e interfaces también sirven como tipos.

Número variable de argumentos con ...$args

...$numbers reúne cualquier número de argumentos en un array. El mismo ... en el lado de quien llama despliega un array en 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 una variable de fuera dentro de una función

Una función tiene su propio ámbito. Una variable definida fuera no es visible dentro, lo que sorprende a quien viene de 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

y la función devuelve el precio sin impuestos. Pasa el valor como parámetro. Así la función deja claro de qué depende y es fácil de probar:

<?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";

La palabra clave global también funciona, pero oculta la dependencia; el ámbito de las variables la explica. Para funciones cortas que se pasan a otras funciones, como los callbacks de array_map(), consulta las funciones anónimas, que pueden capturar variables de fuera con use.