Funzioni in PHP: definire, return, parametri e tipi

Una funzione PHP si definisce con la parola chiave function, un nome, una lista di parametri e un corpo; return restituisce un valore a chi chiama. function add(int $a, int $b): int { return $a + $b; } la definisce, e add(2, 3) la chiama e restituisce 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";

string e int prima dei parametri sono dichiarazioni di tipo, e : string dopo le parentesi è il tipo restituito. Entrambi sono facoltativi, ma intercettano presto gli errori e documentano cosa si aspetta la funzione.

Valori restituiti e restituire più valori

return termina subito la funzione. Una funzione senza return, o con un semplice return;, restituisce null; dichiara : void quando viene chiamata solo per il suo effetto. Una funzione restituisce un solo valore, ma quel valore può essere un array, che destrutturi dal lato di chi chiama:

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

Vedi la destrutturazione degli array per le altre forme di [...] =.

Parametri di default e argomenti con nome

Un parametro con = valore è facoltativo: chi chiama può ometterlo. I parametri facoltativi vanno dopo quelli obbligatori. Da PHP 8.0, gli argomenti con nome permettono a chi chiama di passare qualsiasi parametro tramite il nome, così puoi saltare quelli facoltativi che non ti servono.

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

Gli argomenti con nome rendono leggibili anche le chiamate alle funzioni predefinite: str_pad('7', 3, '0', pad_type: STR_PAD_LEFT). Il nome del parametro diventa parte dell'interfaccia pubblica della funzione, quindi rinominare un parametro può rompere il codice che usa i nomi.

Passaggio per riferimento

Normalmente PHP passa una copia di ogni argomento, quindi la funzione non può modificare la variabile del chiamante. Una & prima di un parametro passa la variabile stessa. Le funzioni predefinite come sort() funzionano così.

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

Restituire un nuovo valore è di solito più chiaro che modificare un argomento. Usa i riferimenti quando la funzione deve davvero modificare qualcosa sul posto.

Dichiarazioni di tipo e strict_types

Di default PHP converte gli argomenti nel tipo dichiarato quando può: add("5", 3) trasforma "5" in 5. Mettere declare(strict_types=1); proprio in cima al file disattiva questo comportamento per le chiamate fatte in quel file, quindi un tipo sbagliato lancia un TypeError invece di essere convertito.

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

Senza la riga declare, la stessa chiamata stampa 8. Le stringhe che non sono numeri, come "five", lanciano un TypeError in entrambe le modalità.

I tipi che puoi dichiarare per parametri e valori restituiti:

<?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 è un tipo restituito per le funzioni che lanciano sempre un'eccezione o terminano lo script. Anche i nomi di classi e interfacce funzionano come tipi.

Numero variabile di argomenti con ...$args

...$numbers raccoglie un numero qualsiasi di argomenti in un array. Gli stessi ... dal lato della chiamata espandono un array in argomenti separati.

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

Usare una variabile esterna dentro una funzione

Una funzione ha il suo scope. Una variabile definita fuori non è visibile dentro, cosa che sorprende chi arriva da 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 la funzione restituisce il prezzo senza tasse. Passa invece il valore come parametro. Così la funzione dichiara chiaramente da cosa dipende ed è facile da testare:

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

Funziona anche la parola chiave global, ma nasconde la dipendenza; lo scope delle variabili la tratta. Per le funzioni brevi passate ad altre funzioni, come le callback di array_map(), vedi le funzioni anonime, che possono catturare variabili esterne con use.