Функции в PHP: объявление, return, параметры и типы

Функция PHP объявляется ключевым словом function, именем, списком параметров и телом; return отправляет значение обратно вызывающему коду. function add(int $a, int $b): int { return $a + $b; } объявляет функцию, а add(2, 3) вызывает её и возвращает 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 и int перед параметрами это объявления типов, а : string после скобок это тип возвращаемого значения. И то, и другое необязательно, но они рано ловят ошибки и документируют, чего функция ожидает.

Возвращаемые значения и возврат нескольких значений

return сразу завершает функцию. Функция без return или с пустым return; возвращает null; объявляйте : void, когда её вызывают только ради действия. Функция возвращает одно значение, но им может быть массив, который вы деструктурируете на стороне вызова:

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

Другие формы [...] = описаны в деструктуризации массива.

Параметры по умолчанию и именованные аргументы

Параметр с = value необязателен: вызывающий код может его опустить. Необязательные параметры идут после обязательных. Начиная с PHP 8.0 именованные аргументы позволяют передать любой параметр по имени, поэтому ненужные необязательные можно пропустить.

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

Именованные аргументы делают читаемыми и вызовы встроенных функций: str_pad('7', 3, '0', pad_type: STR_PAD_LEFT). Имя параметра становится частью публичного интерфейса функции, поэтому переименование параметра может сломать код, который вызывает её по именам.

Передача по ссылке

Обычно PHP передаёт копию каждого аргумента, поэтому функция не может изменить переменную вызывающего кода. & перед параметром передаёт саму переменную. Так работают встроенные функции вроде 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);

Вернуть новое значение обычно понятнее, чем менять аргумент. Используйте ссылки, когда функция действительно должна что-то изменить на месте.

Объявления типов и strict_types

По умолчанию PHP приводит аргументы к объявленному типу, когда может: add("5", 3) превращает "5" в 5. declare(strict_types=1); в самом начале файла отключает это для вызовов из этого файла, и неверный тип выбрасывает TypeError, а не приводится.

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

Без строки declare тот же вызов выводит 8. Строки, которые не являются числами, например "five", выбрасывают TypeError в обоих режимах.

Типы, которые можно объявлять для параметров и возвращаемых значений:

<?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 это тип возвращаемого значения для функций, которые всегда выбрасывают исключение или завершают скрипт. Имена классов и интерфейсов тоже работают как типы.

Переменное число аргументов через ...$args

...$numbers собирает любое число аргументов в массив. Те же ... на стороне вызова распаковывают массив в отдельные аргументы.

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

Внешняя переменная внутри функции

У функции своя область видимости. Переменная, объявленная снаружи, внутри не видна, и это удивляет тех, кто пришёл из 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

и функция возвращает цену без налога. Вместо этого передайте значение параметром. Так функция честно показывает, от чего зависит, и её легко тестировать:

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

Ключевое слово global тоже работает, но прячет зависимость; оно описано в разделе об области видимости переменных. Для коротких функций, которые передаются в другие функции, например колбэков для array_map(), смотрите анонимные функции: они могут захватывать внешние переменные через use.