Fonctions PHP : définir, return, paramètres et types

Une fonction PHP se définit avec le mot-clé function, un nom, une liste de paramètres et un corps ; return renvoie une valeur à l'appelant. function add(int $a, int $b): int { return $a + $b; } la définit, et add(2, 3) l'appelle et renvoie 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";

Les string et int devant les paramètres sont des déclarations de type, et : string après les parenthèses est le type de retour. Les deux sont facultatifs, mais ils détectent les erreurs tôt et documentent ce qu'attend la fonction.

Valeurs de retour et renvoi de plusieurs valeurs

return termine immédiatement la fonction. Une fonction sans return, ou avec un simple return;, renvoie null ; déclarez : void quand elle n'est appelée que pour son effet. Une fonction renvoie une seule valeur, mais cette valeur peut être un tableau, que vous déstructurez du côté de l'appel :

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

Voir la déstructuration de tableau pour les autres formes de [...] =.

Paramètres par défaut et arguments nommés

Un paramètre avec = value est facultatif : l'appelant peut l'omettre. Les paramètres facultatifs se placent après les obligatoires. Depuis PHP 8.0, les arguments nommés permettent à l'appelant de passer n'importe quel paramètre par son nom, et donc de sauter les facultatifs dont il n'a pas besoin.

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

Les arguments nommés rendent aussi lisibles les appels aux fonctions natives : str_pad('7', 3, '0', pad_type: STR_PAD_LEFT). Le nom du paramètre fait alors partie de l'interface publique de la fonction, donc renommer un paramètre peut casser les appels qui utilisent les noms.

Passage par référence

Normalement, PHP passe une copie de chaque argument, donc la fonction ne peut pas modifier la variable de l'appelant. Un & devant un paramètre passe la variable elle-même. Les fonctions natives comme sort() fonctionnent ainsi.

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

Renvoyer une nouvelle valeur est généralement plus clair que modifier un argument. Utilisez les références quand la fonction doit vraiment modifier quelque chose sur place.

Déclarations de type et strict_types

Par défaut, PHP convertit les arguments vers le type déclaré quand il le peut : add("5", 3) transforme "5" en 5. Placer declare(strict_types=1); tout en haut du fichier désactive cela pour les appels faits dans ce fichier, si bien qu'un mauvais type lève une TypeError au lieu d'être converti.

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

Sans la ligne declare, le même appel affiche 8. Les chaînes qui ne sont pas des nombres, comme "five", lèvent une TypeError dans les deux modes.

Les types que vous pouvez déclarer pour les paramètres et les valeurs de retour :

<?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 est un type de retour pour les fonctions qui lèvent toujours une exception ou terminent le script. Les noms de classes et d'interfaces fonctionnent aussi comme types.

Nombre variable d'arguments avec ...$args

...$numbers rassemble un nombre quelconque d'arguments dans un tableau. Le même ... du côté de l'appel décompose un tableau en arguments séparés.

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

Utiliser une variable extérieure dans une fonction

Une fonction a sa propre portée. Une variable définie hors d'elle n'est pas visible à l'intérieur, ce qui surprend ceux qui viennent 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

et la fonction renvoie le prix hors taxes. Passez plutôt la valeur en paramètre. La fonction indique ainsi honnêtement ce dont elle dépend et reste facile à tester :

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

Le mot-clé global fonctionne aussi, mais cache la dépendance ; la portée des variables en parle. Pour les fonctions courtes passées à d'autres fonctions, comme les callbacks d'array_map(), voir les fonctions anonymes, qui peuvent capturer des variables extérieures avec use.