<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: b8f3ae7da35b99b3137ff59aa5d86110dde607f4 Maintainer: sergey Status: ready -->

<!-- Reviewed: no -->

<chapter xml:id="language.functions" xmlns="http://docbook.org/ns/docbook">

<title>Функции</title>

<sect1 xml:id="functions.user-defined">

<title>Пользовательские функции</title>

<para>

Функции определяют ключевым словом <literal>function</literal>,

за которым через пробел идёт название функции и круглые скобки.

Круглые скобки оставляют пустыми или определяют в скобках список параметров; параметры разделяют символом <literal>,</literal>.

За круглыми скобками идёт пара фигурных скобок — тело функции. Приведём пример определения функции:

</para>

<example>

<title>Объявление новой функции с названием <literal>foo</literal></title>

<programlisting role="php">

<![CDATA[

<?php

function foo($arg_1, $arg_2, /* ..., */ $arg_n)

{

echo "Пример функции.\n";

return $retval;

}

?>

]]>

</programlisting>

</example>

<note>

<para>

С PHP 8.0.0 список параметров допускает завершающую запятую:

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

function foo($arg_1, $arg_2,) {}

?>

]]>

</programlisting>

</informalexample>

</para>

</note>

<simpara>

В теле функции записывают корректный PHP-код,

даже другие функции и определения <link linkend="language.oop5.basic.class">классов</link>.

</simpara>

<para>

Имена функций следуют тем же правилам, что и другие метки в PHP.

Корректное имя функции начинается с буквы или знака подчёркивания,

за которым идёт любое количество букв, цифр или знаков

подчёркивания. В виде регулярного выражения имя выражается так:

<code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>.

</para>

&tip.userlandnaming;

<simpara>

Требования объявлять функции раньше появления ссылки на функции — нет,

<emphasis>за исключением</emphasis> условного определения функции,

как показывают два следующих примера.

</simpara>

<para>

Определение функции описывают <emphasis>до</emphasis> вызова функции,

когда функцию определяют по условию, как в двух следующих примерах.

</para>

<para>

<example>

<title>Условные функции</title>

<programlisting role="php">

<![CDATA[

<?php

$makefoo = true;

/* Нельзя вызвать функцию foo() в этом месте,

поскольку функцию ещё не определили, но обращение

к функции bar() доступно */

bar();

if ($makefoo) {

function foo()

{

echo "Я не существую, пока выполнение программы не дойдёт до меня.\n";

}

}

/* Теперь безопасно вызываем функцию foo(),

поскольку выражение переменной $makefoo язык интерпретировал как true */

if ($makefoo) {

foo();

}

function bar()

{

echo "Я существую сразу после запуска программы.\n";

}

?>

]]>

</programlisting>

</example>

</para>

<para>

<example>

<title>Вложенные функции</title>

<programlisting role="php">

<![CDATA[

<?php

function foo()

{

function bar()

{

echo "Я не существую пока не вызовут функцию foo().\n";

}

}

/* Пока нельзя обратиться к функции bar(),

поскольку функцию ещё не определили */

foo();

/* Теперь можно вызвать функцию bar(),

обработка функции foo() сделала её доступной */

bar();

?>

]]>

</programlisting>

</example>

</para>

<para>

У функций и классов PHP глобальная область видимости —

их разрешается вызывать за пределами функции, даже если их определили

внутри, и наоборот.

</para>

<simpara>

PHP не поддерживает перегрузку функций, также невозможно

переопределить или удалить функции, которые объявили раньше.

</simpara>

<note>

<simpara>

Имена функций не зависят от регистра символов в кодировке ASCII

от <literal>A</literal> до <literal>Z</literal>, хотя хорошим тоном

будет вызов функций в том виде, в каком функцию указали в объявлении.

</simpara>

</note>

<simpara>

Функции PHP поддерживают как <link linkend="functions.variable-arg-list">

списки аргументов переменной длины</link>, так и

<link linkend="functions.arguments.default">значения аргументов по умолчанию</link>.

Подробнее об этом рассказывают описания функций

<function>func_num_args</function>,

<function>func_get_arg</function>

и <function>func_get_args</function>.

</simpara>

<para>

В PHP функции разрешается вызывать рекурсивно.

<example>

<title>Рекурсивные функции</title>

<programlisting role="php">

<![CDATA[

<?php

function recursion($a)

{

if ($a < 20) {

echo "$a\n";

recursion($a + 1);

}

}

?>

]]>

</programlisting>

</example>

<note>

<simpara>

Рекурсивный вызов функций и методов с глубиной более 100-200 уровней

рекурсии может вызвать переполнение стека и привести к аварийному

завершению скрипта. В частности, бесконечную рекурсию PHP считает

программной ошибкой.

</simpara>

</note>

</para>

</sect1>

<sect1 xml:id="functions.arguments">

<title>Параметры и аргументы функции</title>

<simpara>

Параметры объявляются в сигнатуре функции. Информацию в параметры функции передают в списке аргументов.

Список аргументов состоит из выражений, которые разделяют запятыми. Выражения

в списке аргументов вычисляются слева направо, а результат вычислений присваивается параметрам

перед действительным вызовом функции. Такое вычисление называется <emphasis>энергичным</emphasis>.

</simpara>

<!-- Note: this paragraph feels like it should be moved to the syntax part? -->

<para>

PHP поддерживает передачу аргументов по значению, это поведение по умолчанию,

и <link linkend="functions.arguments.by-reference">по ссылке</link>,

и <link linkend="functions.arguments.default">значения по умолчанию</link>.

<link linkend="functions.variable-arg-list">Списки аргументов

переменной длины</link> и <link linkend="functions.named-arguments">именованные

аргументы</link> тоже поддерживаются.

</para>

<note>

<para>

С PHP 7.3.0 список аргументов при вызове функций допускает

завершающую запятую:

<informalexample>

<programlisting role="php">

<![CDATA[

<?php

$v = foo(

$arg_1,

$arg_2,

);

?>

]]>

</programlisting>

</informalexample>

</para>

</note>

<para>

Начиная с PHP 8.0.0 список параметров функции допускает завершающую

запятую, которую парсер проигнорирует. Это полезно, когда список параметров

длинный или содержит длинные названия переменных, что в целях удобства подталкивает

к вертикальному перечислению параметров.

</para>

<example>

<title>Список параметров функции с запятой в конце</title>

<programlisting role="php">

<![CDATA[

<?php

function takes_many_args(

$first_arg,

$second_arg,

$a_very_long_argument_name,

$arg_with_default = 5,

$again = 'a default string', // До PHP 8.0.0 указывать запятую в конце списка не разрешали

) {

// ...

}

?>

]]>

</programlisting>

</example>

<sect2 xml:id="functions.arguments.by-reference">

<title>Передача аргументов по ссылке</title>

<simpara>

По умолчанию аргументы передаются в функцию по значению. Поэтому

если значение аргумента внутри функции изменится, значение

переменной, в которой передали аргумент, не изменится за пределами функции.

Аргументы передают по ссылке, чтобы разрешить функции изменять значения аргументов.

</simpara>

<para>

В описании функции перед именем параметра указывают амперсанд &amp;,

когда требуется передача аргумента по ссылке:

</para>

<para>

<example>

<title>Передача аргументов по ссылке</title>

<programlisting role="php">

<![CDATA[

<?php

function add_some_extra(&$string)

{

$string .= 'и кое-что ещё.';

}

$str = 'Это строка, ';

add_some_extra($str);

echo $str; // Конструкция выведет «Это строка, и кое-что ещё.»

?>

]]>

</programlisting>

</example>

</para>

<para>

Передача константного значения в параметр, который ожидает значение по ссылке, вызовет ошибку.

</para>

</sect2>

<sect2 xml:id="functions.arguments.default">

<title>Значения по умолчанию для параметров</title>

<para>

Функция умеет определять для параметров значения по умолчанию,

в этом помогает синтаксис, который похож на синтаксис присваивания значения переменной.

Функция присвоит параметру значение по умолчанию, только если

в параметр не передали аргумент;

обратите внимание, функция <emphasis>не</emphasis> присваивает

параметру значение по умолчанию при передаче в параметр аргумента со значением &null;.

</para>

<para>

<example>

<title>Значения по умолчанию для параметров функций</title>

<programlisting role="php">

<![CDATA[

<?php

function makecoffee($type = "капучино")

{

return "Готовим чашку $type.\n";

}

echo makecoffee();

echo makecoffee(null);

echo makecoffee("эспрессо");

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Готовим чашку капучино.

Готовим чашку .

Готовим чашку эспрессо.

]]>

</screen>

</example>

</para>

<para>

Значениями по умолчанию для параметров разрешается указывать скалярные значения,

массивы (<type>array</type>), специальный тип &null; и начиная с PHP 8.1.0 объекты,

которые создают синтаксисом <link linkend="language.oop5.basic.new">new ClassName()</link>.

</para>

<para>

<example>

<title>Нескалярные типы как значения по умолчанию</title>

<programlisting role="php">

<![CDATA[

<?php

function makecoffee($types = array("капучино"), $coffeeMaker = NULL)

{

$device = is_null($coffeeMaker)

? "вручную"

: $coffeeMaker

;

return "Готовлю чашку " . join(", ", $types) . " $device. \n";

}

echo makecoffee();

echo makecoffee(array("капучино", "лавацца"), "в чайнике");

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Готовлю чашку капучино вручную.

Готовлю чашку капучино, лавацца в чайнике.

]]>

</screen>

</example>

</para>

<para>

<example>

<title>

Объекты как значения по умолчанию, с PHP 8.1.0

</title>

<programlisting role="php">

<![CDATA[

<?php

class DefaultCoffeeMaker

{

public function brew()

{

return "Приготовление кофе.\n";

}

}

class FancyCoffeeMaker

{

public function brew()

{

return "Приготовление прекрасного кофе только для вас.\n";

}

}

function makecoffee($coffeeMaker = new DefaultCoffeeMaker())

{

return $coffeeMaker->brew();

}

echo makecoffee();

echo makecoffee(new FancyCoffeeMaker);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Приготовление кофе.

Приготовление прекрасного кофе только для вас.

]]>

</screen>

</example>

</para>

<simpara>

Объект как значение по умолчанию разрешается определять только константным выражением,

а не переменной, вызовом функции или метода класса.

</simpara>

<para>

Обратите внимание, необязательные параметры потребуется указать

после обязательных, иначе необязательные параметры

не получится пропустить при вызове, поскольку функция рассматривает необязательные параметры,

которые указали перед обязательными, как обязательные.

Рассмотрим следующий пример:

</para>

<para>

<example>

<title>

Неправильное определение значений по умолчанию

для параметров функции

</title>

<programlisting role="php">

<![CDATA[

<?php

function makeyogurt($container = "миску", $flavour)

{

return "Делаем $container с $flavour йогуртом.\n";

}

echo makeyogurt("малиновым"); // Значение «малиновым» получит параметр $container, а не параметр $flavour

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Fatal error: Uncaught ArgumentCountError: Too few arguments

to function makeyogurt(), 1 passed in example.php on line 42

]]>

</screen>

</example>

</para>

<para>

Теперь сравним приведённый пример со следующим примером:

</para>

<para>

<example>

<title>

Правильное определение значений по умолчанию

для параметров функции

</title>

<programlisting role="php">

<![CDATA[

<?php

function makeyogurt($flavour, $container = "миску")

{

return "Делаем $container с $flavour йогуртом.\n";

}

echo makeyogurt("малиновым"); // Значение «малиновым» получит параметр $flavour

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Делаем миску с малиновым йогуртом.

]]>

</screen>

</example>

</para>

<para>

Начиная с PHP 8.0.0 для пропуска необязательных параметров

передают <link linkend="functions.named-arguments">именованные аргументы</link>.

</para>

<para>

<example>

<title>

Правильное определение значений по умолчанию

для параметров функции

</title>

<programlisting role="php">

<![CDATA[

<?php

function makeyogurt($container = "миску", $flavour = "малиновым", $style = "греческим")

{

return "Делаем $container с $flavour $style йогуртом.\n";

}

echo makeyogurt(style: "натуральным");

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Делаем миску с малиновым натуральным йогуртом.

]]>

</screen>

</example>

</para>

<para>

Начиная с PHP 8.0.0 объявление обязательных параметров после необязательных

<emphasis>устарело</emphasis>.

Часто из таких ситуаций выходят путём отказа от значения по умолчанию,

поскольку функция никогда не присвоит параметру, в который передали аргумент,

значение по умолчанию.

Исключение из этого правила — параметры вида <code>Type $param = null</code>,

где значение &null; по умолчанию делает тип неявно обнуляемым.

Такое определение устарело с PHP 8.4.0

и теперь <link linkend="language.types.declarations.nullable">обнуляемый тип</link>

потребуется указать явно.

<example>

<title>

Объявление необязательных параметров после обязательных

</title>

<programlisting role="php">

<![CDATA[

<?php

function foo($a = [], $b) {} // Функция никогда не присвоит значение по умолчанию;

// определение значения по умолчанию для параметра, который идёт

// перед обязательным, устарело с PHP 8.0.0

function foo($a, $b) {} // Определение функционально эквивалентно, но не выдаёт уведомление об устаревании

function bar(A $a = null, $b) {} // С PHP 8.1.0 параметр $a неявно обязателен, поскольку идёт перед обязательным,

// но неявно обнуляем, поскольку для параметра определили значение по умолчанию null.

// Объявления значения по умолчанию null

// без указания обнуляемого типа устарело с PHP 8.4.0

function bar(?A $a, $b) {} // Определение, которое рекомендуют

?>

]]>

</programlisting>

</example>

</para>

<note>

<simpara>

Начиная с PHP 7.1.0 пропуск аргумента для параметра, для которого не задали

значение по умолчанию, выбрасывает исключение

<classname>ArgumentCountError</classname>;

в предыдущих версиях выдавалось предупреждение.

</simpara>

</note>

<note>

<simpara>

Параметрам, которые ожидают аргумент по ссылке,

разрешается устанавливать значения по умолчанию.

</simpara>

</note>

</sect2>

<sect2 xml:id="functions.variable-arg-list">

<title>Списки аргументов переменной длины</title>

<simpara>

В пользовательских функциях PHP поддерживает списки аргументов

переменной длины, параметры для которых определяют оператором из трёх точек

<literal>...</literal>, который называется spread-оператором.

</simpara>

<para>

Списку параметров разрешается содержать оператор

<literal>...</literal>, чтобы показать, что функция принимает переменное

количество аргументов. Переменная получит аргументы как массив:

<example>

<title>

Оператор <literal>...</literal> для доступа к аргументам

</title>

<programlisting role="php">

<![CDATA[

<?php

function sum(...$numbers) {

$acc = 0;

foreach ($numbers as $n) {

$acc += $n;

}

return $acc;

}

echo sum(1, 2, 3, 4);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

10

]]>

</screen>

</example>

</para>

<para>

Spread-оператор <literal>...</literal> указывают также при вызове функции,

чтобы распаковать в список аргументов массив (<type>array</type>),

или распаковать переменную или литерал, которые принадлежат типу

<classname>Traversable</classname>:

<example>

<title>

Передача аргументов со spread-оператором <literal>...</literal>

</title>

<programlisting role="php">

<![CDATA[

<?php

function add($a, $b) {

return $a + $b;

}

echo add(...[1, 2])."\n";

$a = [1, 2];

echo add(...$a);

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

3

3

]]>

</screen>

</example>

</para>

<para>

Стандартные позиционные параметры разрешается указывать перед токеном <literal>...</literal>,

тогда оператор <literal>...</literal> сгенерирует и добавит в массив только конечные аргументы,

которые не соответствуют позиционным.

</para>

<para>

Перед оператором <literal>...</literal> разрешается также добавлять

<link linkend="language.types.declarations">объявление типа</link>.

Тогда функция проверит, что аргументы, которые захватил оператор <literal>...</literal>,

соответствуют типу параметра, или выбросит ошибку.

<example>

<title>Объявление типа для параметра, который ожидает аргументы переменной длины</title>

<programlisting role="php">

<![CDATA[

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

?>

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

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

]]>

</screen>

</example>

</para>

<para>

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

<link linkend="functions.arguments.by-reference">по ссылке</link>,

для этого перед оператором <literal>...</literal> указывают амперсанд

(<literal>&amp;</literal>).

</para>

</sect2>

<sect2 xml:id="functions.named-arguments">

<title>Именованные аргументы</title>

<para>

В PHP 8.0.0 как расширение позиционных параметров появились именованные аргументы.

Именованные аргументы передаются в функцию на основе имени, а не позиции параметра.

Назначение аргумента документирует само себя, аргументы перестают зависеть от порядка,

в котором передаются, и разрешается произвольно пропускать значения по умолчанию.

</para>

<para>

Именованные аргументы передают по названию параметра, за которым идёт

двоеточие и значение аргумента.

Зарезервированные ключевые слова разрешается указывать как имена параметров.

Название параметра потребуется указать как идентификатор, нельзя указывать динамические имена

параметров.

</para>

<example>

<title>Синтаксис именованного аргумента</title>

<programlisting role="php">

<![CDATA[

<?php

myFunction(paramName: $value);

array_foobar(array: $value);

// НЕ поддерживается

function_name($variableStoringParamName: $value);

?>

]]>

</programlisting>

</example>

<example>

<title>

Сравнение позиционных и именованных аргументов

</title>

<programlisting role="php">

<![CDATA[

<?php

// Передача позиционных аргументов:

array_fill(0, 100, 50);

// Передача именованных аргументов:

array_fill(start_index: 0, count: 100, value: 50);

?>

]]>

</programlisting>

</example>

<para>

Порядок передачи именованных аргументов неважен.

</para>

<example>

<title>

Тот же пример, но с другим порядком аргументов

</title>

<programlisting role="php">

<![CDATA[

<?php

array_fill(value: 50, count: 100, start_index: 0);

?>

]]>

</programlisting>

</example>

<para>

Именованные аргументы разрешается комбинировать с позиционными.

Тогда именованные аргументы потребуется передать после позиционных.

Разрешается также передавать только часть необязательных аргументов

функции в произвольном порядке.

</para>

<example>

<title>

Объединение именованных аргументов с позиционными аргументами

</title>

<programlisting role="php">

<![CDATA[

<?php

htmlspecialchars($string, double_encode: false);

// То же самое

htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);

?>

]]>

</programlisting>

</example>

<para>

При передаче именованных аргументов с одним и тем же названием параметра

выбрасывается ошибка <classname>Error</classname>.

</para>

<example>

<title>

Ошибка, которая возникает при передаче нескольких аргументов с названием

одного и того же параметра

</title>

<programlisting role="php">

<![CDATA[

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

?>

]]>

</programlisting>

</example>

<para>

Начиная с PHP 8.1.0 разрешается передавать именованные аргументы

после распаковки аргументов. Именованный аргумент <emphasis>не должен</emphasis>

переопределять распакованный аргумент.

</para>

<example>

<title>

Передача именованных аргументов после распаковки

</title>

<programlisting role="php">

<![CDATA[

<?php

function foo($a, $b, $c = 3, $d = 4) {

return $a + $b + $c + $d;

}

var_dump(foo(...[1, 2], d: 40)); // 46

var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

var_dump(foo(...[1, 2], b: 20)); // Fatal error: Named parameter $b overwrites previous argument

?>

]]>

</programlisting>

</example>

</sect2>

</sect1>

<sect1 xml:id="functions.returning-values">

<title>Возврат значений</title>

<para>

Значения возвращаются необязательной инструкцией возврата.

Разрешается возвращать любой тип, включая массивы и объекты.

Возврат немедленно завершает выполнение функции и передаёт

управление обратно — к той строке кода, в которой вызвали функцию.

Подробную информацию о возврате значений даёт описание инструкции

<function>return</function>.

</para>

<note>

<para>

Функция вернёт значение &null;,

если инструкцию <function>return</function> не указали.

</para>

</note>

<sect2>

<title>Инструкция return</title>

<para>

<example>

<title>

Пример функции с инструкцией <function>return</function>

</title>

<programlisting role="php">

<![CDATA[

<?php

function square($num)

{

return $num * $num;

}

echo square(4); // Выводит 16

?>

]]>

</programlisting>

</example>

</para>

<para>

Функция не умеет возвращать больше одного значения, но аналогичного

результата добиваются возвратом массива.

</para>

<para>

<example>

<title>Возврат набора значений в виде массива</title>

<programlisting role="php">

<![CDATA[

<?php

function small_numbers()

{

return [0, 1, 2];

}

// Деструктуризация массива будет собирать каждый элемент массива индивидуально

[$zero, $one, $two] = small_numbers();

// До версии 7.1.0 единственной эквивалентной альтернативой была языковая конструкция list()

list($zero, $one, $two) = small_numbers();

?>

]]>

</programlisting>

</example>

</para>

<para>

Оператор &amp; указывают и в описании функции,

и в момент присваивания возвращаемого значения переменной,

чтобы функция возвращала результат по ссылке:

</para>

<para>

<example>

<title>Возврат результата по ссылке</title>

<programlisting role="php">

<![CDATA[

<?php

function &returns_reference()

{

return $someref;

}

$newref =& returns_reference();

?>

]]>

</programlisting>

</example>

</para>

<simpara>

Дополнительную информацию о ссылках даёт

раздел документации «<link linkend="language.references">Объяснение ссылок</link>».

</simpara>

</sect2>

</sect1>

<sect1 xml:id="functions.variable-functions">

<title>Функции переменных</title>

<para>

PHP поддерживает концепцию функций переменных. Это означает, что

если к имени переменной присоединили круглые скобки, PHP ищет

функцию с тем же именем, что и результат вычисления переменной,

и пробует выполнить функцию. Этим синтаксисом

описывают callback-функции, таблицы функций и т. д.

</para>

<para>

Функции переменных не работают с языковыми конструкциями

<function>echo</function>, <function>print</function>,

<function>unset</function>, <function>isset</function>,

<function>empty</function>, <function>include</function>,

<function>require</function> и т. п.

Напишите функцию-обёртку, чтобы эти конструкции работали как функции переменных.

</para>

<para>

<example>

<title>Пример функции переменной</title>

<programlisting role="php">

<![CDATA[

<?php

function foo() {

echo "В foo()<br />\n";