Funkcje w PHP: definicja, return, parametry i typy

Funkcję w PHP definiuje się słowem kluczowym function, nazwą, listą parametrów i treścią; return odsyła wartość do wywołującego. function add(int $a, int $b): int { return $a + $b; } ją definiuje, a add(2, 3) wywołuje i zwraca 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 i int przed parametrami to deklaracje typów, a : string po nawiasach to typ zwracany. Oba są opcjonalne, ale wcześnie wyłapują błędy i dokumentują, czego funkcja oczekuje.

Wartości zwracane i zwracanie kilku wartości

return natychmiast kończy funkcję. Funkcja bez return albo z samym return; zwraca null; zadeklaruj : void, gdy wywołujesz ją tylko dla jej efektu. Funkcja zwraca jedną wartość, ale ta wartość może być tablicą, którą destrukturyzujesz po stronie wywołania:

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

Inne formy [...] = opisuje strona o destrukturyzacji tablic.

Parametry domyślne i argumenty nazwane

Parametr z = value jest opcjonalny: wywołujący może go pominąć. Parametry opcjonalne idą po wymaganych. Od PHP 8.0 argumenty nazwane pozwalają przekazać dowolny parametr po nazwie, więc możesz pominąć te opcjonalne, których nie potrzebujesz.

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

Argumenty nazwane poprawiają też czytelność wywołań funkcji wbudowanych: str_pad('7', 3, '0', pad_type: STR_PAD_LEFT). Nazwa parametru staje się częścią publicznego interfejsu funkcji, więc zmiana nazwy parametru może zepsuć wywołania, które używają nazw.

Przekazywanie przez referencję

Zwykle PHP przekazuje kopię każdego argumentu, więc funkcja nie może zmienić zmiennej wywołującego. & przed parametrem przekazuje samą zmienną. Tak działają funkcje wbudowane, takie jak sort().

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

Zwrócenie nowej wartości jest zwykle czytelniejsze niż zmiana argumentu. Używaj referencji, gdy funkcja naprawdę ma coś zmodyfikować w miejscu.

Deklaracje typów i strict_types

Domyślnie PHP konwertuje argumenty na zadeklarowany typ, gdy to możliwe: add("5", 3) zamienia "5" w 5. Umieszczenie declare(strict_types=1); na samej górze pliku wyłącza to dla wywołań w tym pliku, więc zły typ rzuca TypeError zamiast zostać skonwertowany.

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

Bez linii declare to samo wywołanie wypisuje 8. Stringi, które nie są liczbami, takie jak "five", rzucają TypeError w obu trybach.

Typy, które możesz deklarować dla parametrów i wartości zwracanych:

<?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 to typ zwracany dla funkcji, które zawsze rzucają wyjątek albo kończą skrypt. Nazwy klas i interfejsów też działają jako typy.

Zmienna liczba argumentów przez ...$args

...$numbers zbiera dowolną liczbę argumentów w tablicę. To samo ... po stronie wywołania rozpakowuje tablicę na osobne argumenty.

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

Zmienna z zewnątrz wewnątrz funkcji

Funkcja ma własny zasięg. Zmienna zdefiniowana poza nią nie jest widoczna w środku, co zaskakuje osoby przychodzące z JavaScriptu:

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

a funkcja zwraca cenę bez podatku. Zamiast tego przekaż wartość jako parametr. Dzięki temu funkcja uczciwie pokazuje, od czego zależy, i łatwo ją testować:

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

Słowo kluczowe global też działa, ale ukrywa zależność; opisuje je strona o zasięgu zmiennych. Dla krótkich funkcji przekazywanych do innych funkcji, takich jak callbacki dla array_map(), zobacz funkcje anonimowe, które mogą przechwytywać zmienne z zewnątrz przez use.