Аргументы функции
Функция может принимать информацию в виде списка аргументов, который является списком разделенных запятыми выражений. Аргументы вычисляются слева направо.
PHP поддерживает передачу аргументов по значению (по умолчанию), передачу аргументов по ссылке, и значения по умолчанию. Списки аргументов переменной длины также поддерживаются, смотрите также описания функций func_num_args(), func_get_arg() и func_get_args() для более детальной информации.
Пример #1 Передача массива в функцию
<?php
function takes_array($input)
{
echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
?>
Начиная с PHP 8.0.0, список аргументов функции может содержать завершающую запятую, которая будет проигнорирована. Это полезно в случае, когда список аргументов очень длинный, либо если имена переменных длинны, что подталкивает к их вертикальному расположению.
Пример #2 Function Argument List with trailing Comma
<?php
function takes_many_args(
$first_arg,
$second_arg,
$a_very_long_argument_name,
$arg_with_default = 5,
$again = 'a default string', // Эта завершающая запятая допустима только начиная с 8.0.0.
)
{
// ...
}
?>
Начиная с PHP 8.0.0, передача обязательных аргументов после необязательных аргументов
устарела. Обычно это можно решить, отказавшись от значения по умолчанию.
Единственным исключением из этого правила являются аргументы формы
Type $param = null, где null по умолчанию делает тип неявно
допускающим значение null. Это использование остается разрешенным, хотя вместо этого рекомендуется использовать явный тип,
допускающий значение null.
Пример #3 Передача необязательных аргументов после обязательных аргументов
<?php
function foo($a = [], $b) {} // Раньше
function foo($a, $b) {} // Теперь
function bar(A $a = null, $b) {} // Все еще разрешено
function bar(?A $a, $b) {} // Рекомендуется
?>
Передача аргументов по ссылке
По умолчанию аргументы в функцию передаются по значению (это означает, что если вы измените значение аргумента внутри функции, то вне ее значение все равно останется прежним). Если вы хотите разрешить функции модифицировать свои аргументы, вы должны передавать их по ссылке.
Если вы хотите, чтобы аргумент всегда передавался по ссылке, вы можете указать амперсанд (&) перед именем аргумента в описании функции:
Пример #4 Передача аргументов по ссылке
<?php
function add_some_extra(&$string)
{
$string .= 'и кое-что еще.';
}
$str = 'Это строка, ';
add_some_extra($str);
echo $str; // выведет 'Это строка, и кое-что еще.'
?>
Ошибка передачи значения в качестве аргумента, которое должно передаваться по ссылке.
Значения аргументов по умолчанию
Функция может определять значения по умолчанию в стиле C++ для скалярных аргументов, например:
Пример #5 Использование значений по умолчанию в определении функции
<?php
function makecoffee($type = "капучино")
{
return "Готовим чашку $type.\n";
}
echo makecoffee();
echo makecoffee(null);
echo makecoffee("эспрессо");
?>
Результат выполнения данного примера:
Готовим чашку капучино. Готовим чашку . Готовим чашку эспрессо.
PHP также позволяет использовать массивы (array) и специальный тип null в
качестве значений по умолчанию, например:
Пример #6 Использование нескалярных типов в качестве значений по умолчанию
<?php
function makecoffee($types = array("капучино"), $coffeeMaker = NULL)
{
$device = is_null($coffeeMaker) ? "вручную" : $coffeeMaker;
return "Готовлю чашку ".join(", ", $types)." $device.\n";
}
echo makecoffee();
echo makecoffee(array("капучино", "лавацца"), "в чайнике");
?>
Значение по умолчанию должно быть константным выражением, а не (к примеру) переменной или вызовом функции/метода класса.
Обратите внимание, что все аргументы, для которых установлены значения по умолчанию, должны находиться правее аргументов, для которых значения по умолчанию не заданы, в противном случае ваш код может работать не так, как вы этого ожидаете. Рассмотрим следующий пример:
Пример #7 Некорректное использование значений по умолчанию
<?php
function makeyogurt($type = "ацидофил", $flavour)
{
return "Готовим чашку из бактерий $type со вкусом $flavour.\n";
}
echo makeyogurt("малины"); // Не будет работать так, как мы могли бы ожидать
?>
Результат выполнения данного примера:
Warning: Missing argument 2 in call to makeyogurt() in /usr/local/etc/httpd/htdocs/phptest/functest.html on line 41 Готовим чашку из бактерий малины со вкусом .
Теперь сравним его со следующим примером:
Пример #8 Корректное использование значений по умолчанию
<?php
function makeyogurt($flavour, $type = "ацидофил")
{
return "Готовим чашку из бактерий $type со вкусом $flavour.\n";
}
echo makeyogurt("малины"); // отрабатывает правильно
?>
Результат выполнения данного примера:
Готовим чашку из бактерий ацидофил со вкусом малины.
Замечание: Значения по умолчанию могут быть переданы по ссылке.
Списки аргументов переменной длины
PHP поддерживает списки аргументов переменной длины для функций,
определяемых пользователем с помощью добавления
многоточия (...).
Замечание: Также можно добиться аргументов переменной длины, используя функции func_num_args(), func_get_arg() и func_get_args(). Этот метод не рекомендуется, поскольку он использовался до введения. токена
....
Список аргументов может содержать многоточие
..., чтобы показать, что функция принимает переменное
количество аргументов. Аргументы в этом случае будут переданы в виде массива.
Например:
Пример #9 Использование ... для доступа к аргументам
<?php
function sum(...$numbers) {
$acc = 0;
foreach ($numbers as $n) {
$acc += $n;
}
return $acc;
}
echo sum(1, 2, 3, 4);
?>
Результат выполнения данного примера:
10
Многоточие (...) можно использовать при вызове функции,
чтобы распаковать массив (array) или Traversable
переменную в список аргументов:
Пример #10 Использование ... для передачи аргументов
<?php
function add($a, $b) {
return $a + $b;
}
echo add(...[1, 2])."\n";
$a = [1, 2];
echo add(...$a);
?>
Результат выполнения данного примера:
3 3
Можно задать несколько аргументов в привычном виде, а затем добавить
.... В этом случае ... поместит
в массив только те аргументы, которые не нашли соответствия указанным
в объявлении функции.
Также можно добавить
объявление типов перед
.... В этом случае PHP будет следить, чтобы все аргументы
обработанные многоточием (...) были того же типа, что указан в подсказке.
Пример #11 Аргументы с подсказкой типов
<?php
function total_intervals($unit, DateInterval ...$intervals) {
$time = 0;
foreach ($intervals as $interval) {
$time += $interval->$unit;
}
return $time;
}
$a = new DateInterval('P1D');
$b = new DateInterval('P2D');
echo total_intervals('d', $a, $b).' days';
// Это не сработает, т.к. null не является объектом DateInterval.
echo total_intervals('d', null);
?>
Результат выполнения данного примера:
3 days Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2
В конце концов, можно передавать аргументы
по ссылке. Для этого
перед ... нужно поставить амперсанд
(&).
Предыдущие версии PHP
Для указания того, что функция принимает переменное число аргументов, никакой специальный синтаксис не используется. Для доступа к аргументам необходимо использовать функции func_num_args(), func_get_arg() и func_get_args().
В первом примере выше было показано, как задать список аргументов переменной длины для предыдущих версий PHP:
Пример #12 Доступ к аргументам в предыдущих версиях PHP
<?php
function sum() {
$acc = 0;
foreach (func_get_args() as $n) {
$acc += $n;
}
return $acc;
}
echo sum(1, 2, 3, 4);
?>
Результат выполнения данного примера:
10
Именованные аргументы
В PHP 8.0.0 представлены именованные аргументы как расширение существующих позиционных параметров. Именованные аргументы позволяют передавать аргументы функции на основе имени параметра, а не позиции параметра. Это делает значение аргумента самодокументированным, делает аргументы независимыми от порядка и позволяет произвольно пропускать значения по умолчанию.
Именованные аргументы передаются с помощью префикса значения с именем параметра, за которым следует двоеточие. Допускается использование зарезервированных ключевых слов в качестве имен параметров. Имя параметра должно быть идентификатором, динамическое указание не допускается.
Пример #13 Синтаксис именованного аргумента
<?php
myFunction(paramName: $value);
array_foobar(array: $value);
// НЕ поддерживается
function_name($variableStoringParamName: $value);
?>
Пример #14 Позиционные аргументы против именованных аргументов
<?php
// Использование позиционных аргументов:
array_fill(0, 100, 50);
// Использование именованных аргументов:
array_fill(start_index: 0, num: 100, value: 50);
?>
Порядок, в котором передаются названные аргументы, не имеет значения.
Пример #15 Тот же пример, что и выше, с другим порядком параметров
<?php
array_fill(value: 50, num: 100, start_index: 0);
?>
Именованные аргументы можно комбинировать с позиционными аргументами. В этом случае именованные аргументы должны идти после позиционных аргументов. Также возможно указать только некоторые из необязательных аргументов функции, независимо от их порядка.
Пример #16 Объединение именованных аргументов с позиционными аргументами
<?php
htmlspecialchars($string, double_encode: false);
// То же самое
htmlspecialchars($string, ENT_COMPAT | ENT_HTML401, 'UTF-8', false);
?>
Передача одного и того же параметра несколько раз приводит к выбрасыванию исключения Error.
Пример #17 Исключение Error при передаче одного и того же параметра несколько раз
<?php
function foo($param) { ... }
foo(param: 1, param: 2);
// Error: Named parameter $param overwrites previous argument
foo(1, param: 2);
// Error: Named parameter $param overwrites previous argument
?>