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

<!-- $Revision$ -->

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

<title>Functions</title>

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

<title>User-defined functions</title>

<para>

A function is defined using the <literal>function</literal> keyword,

a name, a list of parameters (which might be empty) separated by commas

(<literal>,</literal>) enclosed in parentheses, followed by the body of

the function enclosed in curly braces, such as the following:

</para>

<example>

<title>Declaring a new function named <literal>foo</literal></title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

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

{

echo "Example function.\n";

return $retval;

}

]]>

</programlisting>

</example>

<note>

<para>

As of PHP 8.0.0, the list of parameters may have a trailing comma:

<informalexample>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

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

]]>

</programlisting>

</informalexample>

</para>

</note>

<simpara>

Any valid PHP code may appear inside the body of a function, even other

functions and <link linkend="language.oop5.basic.class">class</link>

definitions.

</simpara>

<para>

Function names follow the same rules as other labels in PHP. A

valid function name starts with a letter or underscore, followed

by any number of letters, numbers, or underscores. As a regular

expression, it would be expressed thus:

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

</para>

&tip.userlandnaming;

<simpara>

Functions need not be defined before they are referenced,

<emphasis>except</emphasis> when a function is conditionally defined as

shown in the two examples below.

</simpara>

<para>

When a function is defined in a conditional manner such as the two

examples shown. Its definition must be processed <emphasis>prior</emphasis>

to being called.

</para>

<para>

<example>

<title>Conditional functions</title>

<programlisting role="php">

<![CDATA[

<?php

$makefoo = true;

/* We can't call foo() from here

since it doesn't exist yet,

but we can call bar() */

if (function_exists('foo')) {

foo();

} else {

echo "Function foo does not exist (yet).\n";

}

bar();

if ($makefoo) {

function foo()

{

echo "I don't exist until program execution reaches me.\n";

}

}

/* Now we can safely call foo()

since $makefoo evaluated to true */

if ($makefoo) foo();

function bar()

{

echo "I exist immediately upon program start.\n";

}

]]>

</programlisting>

</example>

</para>

<para>

<example>

<title>Functions within functions</title>

<programlisting role="php">

<![CDATA[

<?php

function foo()

{

function bar()

{

echo "I don't exist until foo() is called.\n";

}

}

/* We can't call bar() yet

since it doesn't exist. */

if (function_exists('bar')) {

bar();

}

foo();

/* Now we can call bar(),

foo()'s processing has

made it accessible. */

bar();

]]>

</programlisting>

</example>

</para>

<para>

All functions and classes in PHP have the global scope - they can be

called outside a function even if they were defined inside and vice versa.

</para>

<simpara>

PHP does not support function overloading, nor is it possible to

undefine or redefine previously-declared functions.

</simpara>

<note>

<simpara>

Function names are case-insensitive for the ASCII characters <literal>A</literal> to <literal>Z</literal>, though it is usually good form

to call functions as they appear in their declaration.

</simpara>

</note>

<simpara>

Both <link linkend="functions.variable-arg-list">variable number of

arguments</link> and <link linkend="functions.arguments.default">default

arguments</link> are supported in functions. See also the function

references for

<function>func_num_args</function>,

<function>func_get_arg</function>, and

<function>func_get_args</function> for more information.

</simpara>

<para>

It is possible to call recursive functions in PHP.

<example>

<title>Recursive functions</title>

<programlisting role="php">

<![CDATA[

<?php

function recursion($a)

{

if ($a < 20) {

echo "$a\n";

recursion($a + 1);

}

}

recursion(17);

]]>

</programlisting>

</example>

<note>

<simpara>

Recursive function/method calls with over 100-200 recursion levels can

smash the stack and cause a termination of the current script. Especially,

infinite recursion is considered a programming error.

</simpara>

</note>

</para>

</sect1>

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

<title>Function parameters and arguments</title>

<simpara>

The function parameters are declared in the function signature.

Information may be passed to functions via the argument list,

which is a comma-delimited list of expressions. The arguments are

evaluated from left to right and the result is assigned to the parameters of

the function, before the function is actually called

(<emphasis>eager</emphasis> evaluation).

</simpara>

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

<para>

PHP supports passing arguments by value (the default), <link

linkend="functions.arguments.by-reference">passing by

reference</link>, and <link

linkend="functions.arguments.default">default argument

values</link>. <link linkend="functions.variable-arg-list">Variable-length

argument lists</link> and <link linkend="functions.named-arguments">Named Arguments</link>

are also supported.

</para>

<note>

<para>

As of PHP 7.3.0, it is possible to have a trailing comma in the argument

list for a function calls:

<informalexample>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

$v = foo(

$arg_1,

$arg_2,

);

]]>

</programlisting>

</informalexample>

</para>

</note>

<para>

As of PHP 8.0.0, the list of function parameters may include a trailing comma, which

will be ignored. That is particularly useful in cases where the list of parameters is

long or contains long variable names, making it convenient to list parameters vertically.

</para>

<example>

<title>Function parameter list with trailing comma</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

function takes_many_args(

$first_arg,

$second_arg,

$a_very_long_argument_name,

$arg_with_default = 5,

$again = 'a default string', // This trailing comma was not permitted before 8.0.0.

)

{

// ...

}

]]>

</programlisting>

</example>

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

<title>Passing arguments by reference</title>

<simpara>

By default, function arguments are passed by value (so that if

the value of the argument within the function is changed, it does

not get changed outside of the function). To allow a function to modify its

arguments, they must be passed by reference.

</simpara>

<para>

To have an argument to a function always passed by reference, prepend an

ampersand (&amp;) to the parameter name in the function definition:

</para>

<para>

<example>

<title>Passing function arguments by reference</title>

<programlisting role="php">

<![CDATA[

<?php

function add_some_extra(&$string)

{

$string .= 'and something extra.';

}

$str = 'This is a string, ';

add_some_extra($str);

echo $str; // outputs 'This is a string, and something extra.'

]]>

</programlisting>

</example>

</para>

<para>

It is an error to pass a constant expression as an argument to a parameter

that expects to be passed by reference.

</para>

</sect2>

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

<title>Default parameter values</title>

<para>

A function may define default values for parameters using syntax similar

to assigning a variable. The default is used only when the parameter's argument is

not passed. Note that passing &null; does <emphasis>not</emphasis>

assign the default value.

</para>

<para>

<example>

<title>Use of default parameters in functions</title>

<programlisting role="php">

<![CDATA[

<?php

function makecoffee($type = "cappuccino")

{

return "Making a cup of $type.\n";

}

echo makecoffee();

echo makecoffee(null);

echo makecoffee("espresso");

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Making a cup of cappuccino.

Making a cup of .

Making a cup of espresso.

]]>

</screen>

</example>

</para>

<para>

Default parameter values may be scalar values, <type>array</type>s,

the special type &null;, and as of PHP 8.1.0, objects using the

<link linkend="language.oop5.basic.new">new ClassName()</link> syntax.

</para>

<para>

<example>

<title>Using non-scalar types as default values</title>

<programlisting role="php">

<![CDATA[

<?php

function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)

{

$device = is_null($coffeeMaker) ? "hands" : $coffeeMaker;

return "Making a cup of ".join(", ", $types)." with $device.\n";

}

echo makecoffee();

echo makecoffee(array("cappuccino", "lavazza"), "teapot");

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Making a cup of cappuccino with hands.

Making a cup of cappuccino, lavazza with teapot.

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Using objects as default values (as of PHP 8.1.0)</title>

<programlisting role="php">

<![CDATA[

<?php

class DefaultCoffeeMaker {

public function brew() {

return "Making coffee.\n";

}

}

class FancyCoffeeMaker {

public function brew() {

return "Crafting a beautiful coffee just for you.\n";

}

}

function makecoffee($coffeeMaker = new DefaultCoffeeMaker)

{

return $coffeeMaker->brew();

}

echo makecoffee();

echo makecoffee(new FancyCoffeeMaker);

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Making coffee.

Crafting a beautiful coffee just for you.

]]>

</screen>

</example>

</para>

<simpara>

The default value must be a constant expression, not (for

example) a variable, a class member or a function call.

</simpara>

<para>

Note that any optional parameters should be specified after any

required parameters, otherwise they cannot be omitted from calls.

Consider the following example:

</para>

<para>

<example>

<title>Incorrect usage of default function parameters</title>

<programlisting role="php">

<![CDATA[

<?php

function makeyogurt($container = "bowl", $flavour)

{

return "Making a $container of $flavour yogurt.\n";

}

echo makeyogurt("raspberry"); // "raspberry" is $container, not $flavour

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Deprecated: makeyogurt(): Optional parameter $container declared before required parameter $flavour is implicitly treated as a required parameter in script on line 2

Fatal error: Uncaught ArgumentCountError: Too few arguments to function makeyogurt(), 1 passed in script on line 7 and exactly 2 expected in script:2

Stack trace:

#0 script(7): makeyogurt('raspberry')

#1 {main}

thrown in script on line 2

]]>

</screen>

</example>

</para>

<para>

Now, compare the above with this:

</para>

<para>

<example>

<title>Correct usage of default function parameters</title>

<programlisting role="php">

<![CDATA[

<?php

function makeyogurt($flavour, $container = "bowl")

{

return "Making a $container of $flavour yogurt.\n";

}

echo makeyogurt("raspberry"); // "raspberry" is $flavour

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Making a bowl of raspberry yogurt.

]]>

</screen>

</example>

</para>

<para>

As of PHP 8.0.0, <link linkend="functions.named-arguments">named arguments</link>

can be used to skip over multiple optional parameters.

</para>

<para>

<example>

<title>Correct usage of default function parameters</title>

<programlisting role="php">

<![CDATA[

<?php

function makeyogurt($container = "bowl", $flavour = "raspberry", $style = "Greek")

{

return "Making a $container of $flavour $style yogurt.\n";

}

echo makeyogurt(style: "natural");

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

Making a bowl of raspberry natural yogurt.

]]>

</screen>

</example>

</para>

<para>

As of PHP 8.0.0, declaring mandatory parameters after optional parameters

is <emphasis>deprecated</emphasis>. This can generally be resolved by

dropping the default value, since it will never be used.

One exception to this rule are parameters of the form

<code>Type $param = null</code>, where the &null; default makes the type implicitly

nullable. This usage is deprecated as of PHP 8.4.0, and an explicit

<link linkend="language.types.declarations.nullable">nullable type</link>

should be used instead.

<example>

<title>Declaring optional parameters after mandatory parameters</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

function foo($a = [], $b) {} // Default not used; deprecated as of PHP 8.0.0

function foo($a, $b) {} // Functionally equivalent, no deprecation notice

function bar(A $a = null, $b) {} // As of PHP 8.1.0, $a is implicitly required

// (because it comes before the required one),

// but implicitly nullable (deprecated as of PHP 8.4.0),

// because the default parameter value is null

function bar(?A $a, $b) {} // Recommended

]]>

</programlisting>

</example>

</para>

<note>

<simpara>

As of PHP 7.1.0, omitting a parameter which does not specify a default

throws an <classname>ArgumentCountError</classname>; in previous versions

it raised a Warning.

</simpara>

</note>

<note>

<simpara>

Parameters that expect the argument by reference may have a default value.

</simpara>

</note>

</sect2>

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

<title>Variable-length argument lists</title>

<simpara>

PHP has support for variable-length argument lists in

user-defined functions by using the

<literal>...</literal> token.

</simpara>

<para>

Parameter lists may include the

<literal>...</literal> token to denote that the function accepts a

variable number of arguments. The arguments will be passed into the

given variable as an &array;:

<example>

<title>Using <literal>...</literal> to access variable arguments</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>

<literal>...</literal> can also be used when calling functions to unpack

an <type>array</type> or <classname>Traversable</classname> variable or

literal into the argument list:

<example>

<title>Using <literal>...</literal> to provide arguments</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>

You may specify normal positional parameters before the

<literal>...</literal> token. In this case, only the trailing arguments

that don't match a positional argument will be added to the array

generated by <literal>...</literal>.

</para>

<para>

It is also possible to add a

<link linkend="language.types.declarations">type declaration</link> before the

<literal>...</literal> token. If this is present, then all arguments

captured by <literal>...</literal> must match that parameter type.

<example>

<title>Type declared variable arguments</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';

// This will fail, since null isn't a DateInterval object.

echo total_intervals('d', null);

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

3 days

Fatal error: Uncaught TypeError: total_intervals(): Argument #2 must be of type DateInterval, null given, called in script on line 15 and defined in script:2

Stack trace:

#0 script(15): total_intervals('d', NULL)

#1 {main}

thrown in script on line 2

]]>

</screen>

</example>

</para>

<para>

Finally, variable arguments can also be passed

<link linkend="functions.arguments.by-reference">by reference</link> by

prefixing the <literal>...</literal> with an ampersand

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

</para>

</sect2>

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

<title>Named Arguments</title>

<para>

PHP 8.0.0 introduced named arguments as an extension of the existing

positional parameters. Named arguments allow passing arguments to a

function based on the parameter name, rather than the parameter position.

This makes the meaning of the argument self-documenting, makes the

arguments order-independent and allows skipping default values arbitrarily.

</para>

<para>

Named arguments are passed by prefixing the value with the parameter name

followed by a colon. Using reserved keywords as parameter names is allowed.

The parameter name must be an identifier, specifying dynamically

is not allowed.

</para>

<example>

<title>Named argument syntax</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

myFunction(paramName: $value);

array_foobar(array: $value);

// NOT supported.

function_name($variableStoringParamName: $value);

]]>

</programlisting>

</example>

<example>

<title>Positional arguments versus named arguments</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

// Using positional arguments:

array_fill(0, 100, 50);

// Using named arguments:

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

]]>

</programlisting>

</example>

<para>

The order in which the named arguments are passed does not matter.

</para>

<example>

<title>Same example as above with a different order of parameters</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

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

]]>

</programlisting>

</example>

<para>

Named arguments can be combined with positional arguments. In this case,

the named arguments must come after the positional arguments.

It is also possible to specify only some of the optional arguments of a

function, regardless of their order.

</para>

<example>

<title>Combining named arguments with positional arguments</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

htmlspecialchars($string, double_encode: false);

// Same as

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

]]>

</programlisting>

</example>

<para>

Passing an argument to the same named parameter multiple times results in an

<classname>Error</classname> exception.

</para>

<example>

<title>Error thrown when passing an argument to the same named parameter multiple times</title>

<programlisting role="php" annotations="non-interactive">

<![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>

As of PHP 8.1.0, it is possible to use named arguments after unpacking the arguments.

A named argument <emphasis>must not</emphasis> override an already unpacked argument.

</para>

<example>

<title>Use named arguments after unpacking</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>

<simpara>

Some internal functions document an alternative signature, such as

<function>session_set_save_handler</function>, whose parameter names do not

exist in the function itself. These names cannot be used as named

arguments and result in an error.

</simpara>

</sect2>

</sect1>

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

<title>Returning values</title>

<para>

Values are returned by using the optional return statement. Any

type may be returned, including arrays and objects. This causes the

function to end its execution immediately and pass control back to

the line from which it was called. See <function>return</function>

for more information.

</para>

<note>

<para>

If the <function>return</function> is omitted the value &null; will be

returned.

</para>

</note>

<sect2>

<title>Use of return</title>

<para>

<example>

<title>Use of <function>return</function></title>

<programlisting role="php">

<![CDATA[

<?php

function square($num)

{

return $num * $num;

}

echo square(4); // outputs '16'.

]]>

</programlisting>

</example>

</para>

<para>

A function can not return multiple values, but similar results can be

obtained by returning an array.

</para>

<para>

<example>

<title>Returning an array to get multiple values</title>

<programlisting role="php">

<![CDATA[

<?php

function small_numbers()

{

return [0, 1, 2];

}

// Array destructuring will collect each member of the array individually

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

var_dump($zero, $one, $two);

// Prior to 7.1.0, the only equivalent alternative is using list() construct

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

]]>

</programlisting>

</example>

</para>

<para>

To return a reference from a function, use the reference operator &amp; in

both the function declaration and when assigning the returned value to a

variable:

</para>

<para>

<example>

<title>Returning a reference from a function</title>

<programlisting role="php" annotations="non-interactive">

<![CDATA[

<?php

function &returns_reference()

{

return $someref;

}

$newref =& returns_reference();

]]>

</programlisting>

</example>

</para>

<simpara>

For more information on references, please check out <link

linkend="language.references">References Explained</link>.

</simpara>

</sect2>

</sect1>

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

<title>Variable functions</title>

<para>

PHP supports the concept of variable functions. This means that if

a variable name has parentheses appended to it, PHP will look for

a function with the same name as whatever the variable evaluates

to, and will attempt to execute it. Among other things, this can

be used to implement callbacks, function tables, and so forth.

</para>

<para>

Variable functions won't work with language constructs such

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

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

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

<function>require</function> and the like. Utilize wrapper functions to make

use of any of these constructs as variable functions.

</para>

<para>

<example>

<title>Variable function example</title>

<programlisting role="php">

<![CDATA[

<?php

function foo() {

echo "In foo()\n";

}

function bar($arg = '')

{

echo "In bar(); argument was '$arg'.\n";

}

// This is a wrapper function around echo

function echoit($string)

{

echo $string;

}

$func = 'foo';

$func(); // This calls foo()

$func = 'bar';

$func('test'); // This calls bar()

$func = 'echoit';

$func('test'); // This calls echoit()

]]>

</programlisting>

</example>

</para>

<para>

Object methods can also be called with the variable functions syntax.

<example>

<title>Variable method example</title>

<programlisting role="php">

<![CDATA[

<?php

class Foo

{

function Variable()

{

$name = 'Bar';

$this->$name(); // This calls the Bar() method

}

function Bar()

{

echo "This is Bar";

}

}

$foo = new Foo();

$funcname = "Variable";

$foo->$funcname(); // This calls $foo->Variable()

]]>

</programlisting>

</example>

</para>

<para>

When calling static methods, the function call is stronger than the static property operator:

<example>

<title>Variable method example with static properties</title>

<programlisting role="php">

<![CDATA[

<?php

class Foo

{

static $variable = 'static property';

static function Variable()

{

echo "Method Variable called\n";

}

}

echo Foo::$variable ."\n"; // This prints 'static property'. It does need a $variable in this scope.

$variable = "Variable";

Foo::$variable(); // This calls $foo->Variable() reading $variable in this scope.

]]>

</programlisting>

&example.outputs;

<screen>

<![CDATA[

static property

Method Variable called

]]>

</screen>

</example>

</para>

<para>

<example>

<title>Complex callables</title>

<programlisting role="php">

<![CDATA[

<?php

class Foo

{

static function bar()

{

echo "bar\n";

}

function baz()

{

echo "baz\n";

}

}

$func = array("Foo", "bar");

$func(); // prints "bar"

$func = array(new Foo, "baz");

$func(); // prints "baz"

$func = "Foo::bar";

$func(); // prints "bar"

]]>

</programlisting>

</example>

</para>

<sect2 role="seealso">

&reftitle.seealso;

<para>