php-doc-en/language/functions.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <chapter xml:id="language.functions" xmlns="http://docbook.org/ns/docbook">
  <title>Functions</title>

  <sect1 xml:id="functions.user-defined">
   <title>User-defined functions</title>
 
   <para>
    A function may be defined using syntax such as the following:
   </para>
   <para>
    <example>
     <title>Pseudo code to demonstrate function uses</title>
     <programlisting role="php">
<![CDATA[
<?php
function foo($arg_1, $arg_2, /* ..., */ $arg_n)
{
    echo "Example function.\n";
    return $retval;
}
?>
]]>
     </programlisting>
    </example>
   </para>
   
   <simpara>
    Any valid PHP code may appear inside 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:
    <literal>[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*</literal>.
   </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() */

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. */

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, 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);
    }
}
?>
]]>
     </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 arguments</title>
 
   <simpara>
    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.
   </simpara>

   <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> are also supported.
   </para>
   <para>
    <example>
     <title>Passing arrays to functions</title>
     <programlisting role="php">
<![CDATA[
<?php
function takes_array($input)
{
    echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
?>
]]>
     </programlisting>
    </example>
   </para>   
   <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 argument name in the function definition:
    </para>
    <para>
     <example>
      <title>Passing function parameters 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>
   </sect2>
   <sect2 xml:id="functions.arguments.default">
    <title>Default argument values</title>
 
    <para>
     A function may define C++-style default values for scalar
     arguments as follows:
    </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>
     PHP also allows the use of <type>array</type>s and the special type &null;
     as default values, for example:
    </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>
    
    </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 when using default arguments, any defaults should be on
     the right side of any non-default arguments; otherwise, things
     will not work as expected. Consider the following code snippet:
    </para>
    <para>
     <example>
      <title>Incorrect usage of default function arguments</title>
      <programlisting role="php">
<![CDATA[
<?php
function makeyogurt($type = "acidophilus", $flavour)
{
    return "Making a bowl of $type $flavour.\n";
}
 
echo makeyogurt("raspberry");   // won't work as expected
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Warning: Missing argument 2 in call to makeyogurt() in 
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Making a bowl of raspberry .
]]>
      </screen>
     </example>
    </para>
    <para>
     Now, compare the above with this:
    </para>
    <para>
     <example>
      <title>Correct usage of default function arguments</title>
      <programlisting role="php">
<![CDATA[
<?php
function makeyogurt($flavour, $type = "acidophilus")
{
    return "Making a bowl of $type $flavour.\n";
}
 
echo makeyogurt("raspberry");   // works as expected
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Making a bowl of acidophilus raspberry.
]]>
      </screen>
     </example>
    </para>
    <note>
     <simpara>
      As of PHP 5, arguments that are passed by reference may have a default value.
     </simpara>
    </note>
   </sect2>

   <sect2 xml:id="functions.arguments.type-declaration">
    <title>Type declarations</title>

    <note>
     <para>
      Type declarations were also known as type hints in PHP 5.
     </para>
    </note>

    <para>
     Type declarations allow functions to require that parameters are of a certain type at call time.
     If the given value is of the incorrect type,
     then an error is generated: in PHP 5, this will be a recoverable fatal
     error, while PHP 7 will throw a <classname>TypeError</classname>
     exception.
    </para>

    <para>
     To specify a type declaration, the type name should be added before the
     parameter name. The declaration can be made to accept &null; values if
     the default value of the parameter is set to &null;.
    </para>

    <sect3 xml:id="functions.arguments.type-declaration.types">
     <title>Valid types</title>
     <informaltable>
      <tgroup cols="3">
       <thead>
        <row>
         <entry>Type</entry>
         <entry>Description</entry>
         <entry>Minimum PHP version</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>Class/interface name</entry>
         <entry>
          The parameter must be an &instanceof; the given class or interface
          name.
         </entry>
         <entry>PHP 5.0.0</entry>
        </row>
        <row>
         <entry><literal>self</literal></entry>
         <entry>
          The parameter must be an &instanceof; the same class as the one the
          method is defined on. This can only be used on class and instance
          methods.
         </entry>
         <entry>PHP 5.0.0</entry>
        </row>
        <row>
         <entry><type>array</type></entry>
         <entry>
          The parameter must be an <type>array</type>.
         </entry>
         <entry>PHP 5.1.0</entry>
        </row>
        <row>
         <entry><type>callable</type></entry>
         <entry>
          The parameter must be a valid <type>callable</type>.
         </entry>
         <entry>PHP 5.4.0</entry>
        </row>
        <row>
         <entry><type>bool</type></entry>
         <entry>
          The parameter must be a <type>boolean</type> value.
         </entry>
         <entry>PHP 7.0.0</entry>
        </row>
        <row>
         <entry><type>float</type></entry>
         <entry>
          The parameter must be a <type>float</type>ing point number.
         </entry>
         <entry>PHP 7.0.0</entry>
        </row>
        <row>
         <entry><type>int</type></entry>
         <entry>
          The parameter must be an <type>integer</type>.
         </entry>
         <entry>PHP 7.0.0</entry>
        </row>
        <row>
         <entry><type>string</type></entry>
         <entry>
          The parameter must be a <type>string</type>.
         </entry>
         <entry>PHP 7.0.0</entry>
        </row>
        <row>
         <entry><literal>iterable</literal></entry>
         <entry>
          The parameter must be either an <type>array</type> or an &instanceof; <classname>Traversable</classname>.
         </entry>
         <entry>PHP 7.1.0</entry>
        </row>
        <row>
         <entry><literal>object</literal></entry>
         <entry>
          The parameter must be an <type>object</type>.
         </entry>
         <entry>PHP 7.2.0</entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>

     <warning>
      <para>
       Aliases for the above scalar types are not supported. Instead, they are
       treated as class or interface names. For example, using
       <literal>boolean</literal> as a parameter or return type will require
       an argument or return value that is an &instanceof; the class or
       interface <literal>boolean</literal>, rather than of type
       <type>bool</type>:
      </para>
      <para>
       <example>
        <programlisting role="php">
 <![CDATA[
 <?php
 function test(boolean $param) {}
 test(true);
 ?>
 ]]>
        </programlisting>
        &example.outputs;
        <screen>
 <![CDATA[
 Fatal error: Uncaught TypeError: Argument 1 passed to test() must be an instance of boolean, boolean given, called in - on line 1 and defined in -:1
 ]]>
        </screen>
       </example>
      </para>
     </warning>
    </sect3>

    <sect3 xml:id="functions.arguments.type-declaration.examples">
     &reftitle.examples;
     <example>
      <title>Basic class type declaration</title>
      <programlisting role="php">
<![CDATA[
<?php
class C {}
class D extends C {}

// This doesn't extend C.
class E {}

function f(C $c) {
    echo get_class($c)."\n";
}

f(new C);
f(new D);
f(new E);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
C
D

Fatal error: Uncaught TypeError: Argument 1 passed to f() must be an instance of C, instance of E given, called in - on line 14 and defined in -:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
  thrown in - on line 8
]]>
      </screen>
     </example>

     <example>
      <title>Basic interface type declaration</title>
      <programlisting role="php">
<![CDATA[
<?php
interface I { public function f(); }
class C implements I { public function f() {} }

// This doesn't implement I.
class E {}

function f(I $i) {
    echo get_class($i)."\n";
}

f(new C);
f(new E);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
C

Fatal error: Uncaught TypeError: Argument 1 passed to f() must implement interface I, instance of E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
  thrown in - on line 8
]]>
      </screen>
     </example>

     <example>
      <title>Nullable type declaration</title>
      <programlisting role="php">
<![CDATA[
<?php
class C {}

function f(C $c = null) {
    var_dump($c);
}

f(new C);
f(null);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
object(C)#1 (0) {
}
NULL
]]>
      </screen>
     </example>
    </sect3>

    <sect3 xml:id="functions.arguments.type-declaration.strict">
     <title>Strict typing</title>

     <para>
      By default, PHP will coerce values of the wrong type into the expected
      scalar type if possible. For example, a function that is given an
      <type>integer</type> for a parameter that expects a <type>string</type>
      will get a variable of type <type>string</type>.
     </para>

     <para>
      It is possible to enable strict mode on a per-file basis. In strict
      mode, only a variable of exact type of the type declaration will be
      accepted, or a <classname>TypeError</classname> will be thrown. The
      only exception to this rule is that an <type>integer</type> may be given
      to a function expecting a <type>float</type>. Function calls from within
      internal functions will not be affected by the <literal>strict_types</literal>
      declaration.
     </para>

     <para>
      To enable strict mode, the &declare; statement is used with the
      <literal>strict_types</literal> declaration:
     </para>

     <caution>
      <para>
       Enabling strict mode will also affect
       <link linkend="functions.returning-values.type-declaration">return type declarations</link>.
      </para>
     </caution>

     <note>
      <para>
       Strict typing applies to function calls made from
       <emphasis>within</emphasis> the file with strict typing enabled, not to
       the functions declared within that file. If a file without strict
       typing enabled makes a call to a function that was defined in a file
       with strict typing, the caller's preference (weak typing) will be
       respected, and the value will be coerced.
      </para>
     </note>

     <note>
      <para>
       Strict typing is only defined for scalar type declarations, and as
       such, requires PHP 7.0.0 or later, as scalar type declarations were
       added in that version.
      </para>
     </note>

     <example>
      <title>Strict typing</title>
      <programlisting role="php">
<![CDATA[
<?php
declare(strict_types=1);

function sum(int $a, int $b) {
    return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1.5, 2.5));
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
int(3)

Fatal error: Uncaught TypeError: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
  thrown in - on line 4
]]>
      </screen>
     </example>

     <example>
      <title>Weak typing</title>
      <programlisting role="php">
<![CDATA[
<?php
function sum(int $a, int $b) {
    return $a + $b;
}

var_dump(sum(1, 2));

// These will be coerced to integers: note the output below!
var_dump(sum(1.5, 2.5));
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
int(3)
int(3)
]]>
      </screen>
     </example>

     <example>
      <title>Catching <classname>TypeError</classname></title>
      <programlisting role="php">
<![CDATA[
<?php
declare(strict_types=1);

function sum(int $a, int $b) {
    return $a + $b;
}

try {
    var_dump(sum(1, 2));
    var_dump(sum(1.5, 2.5));
} catch (TypeError $e) {
    echo 'Error: '.$e->getMessage();
}
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
int(3)
Error: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 10
]]>
      </screen>
     </example>
    </sect3>
   </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. This is implemented using the
     <literal>...</literal> token in PHP 5.6 and later, and using the
     <function>func_num_args</function>,
     <function>func_get_arg</function>, and
     <function>func_get_args</function> functions in PHP 5.5 and earlier.
    </simpara>

    <sect3 xml:id="functions.variable-arg-list.new">
     <title><literal>...</literal> in PHP 5.6+</title>

     <para>
      In PHP 5.6 and later, argument 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; for example:

      <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>
      You can also use <literal>...</literal> 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 arguments 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.oop5.typehinting">type hint</link> before the
      <literal>...</literal> token. If this is present, then all arguments
      captured by <literal>...</literal> must be objects of the hinted class.

      <example>
       <title>Type hinted 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
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>
      Finally, you may also pass variable arguments
      <link linkend="functions.arguments.by-reference">by reference</link> by
      prefixing the <literal>...</literal> with an ampersand
      (<literal>&amp;</literal>).
     </para>
    </sect3>

    <sect3 xml:id="functions.variable-arg-list.old">
     <title>Older versions of PHP</title>

     <para>
      No special syntax is required to note that a function is variadic;
      however access to the function's arguments must use
      <function>func_num_args</function>, <function>func_get_arg</function>
      and <function>func_get_args</function>.
     </para>

     <para>
      The first example above would be implemented as follows in PHP 5.5 and
      earlier:

      <example>
       <title>Accessing variable arguments in PHP 5.5 and earlier</title>
       <programlisting role="php">
<![CDATA[
<?php
function sum() {
    $acc = 0;
    foreach (func_get_args() as $n) {
        $acc += $n;
    }
    return $acc;
}

echo sum(1, 2, 3, 4);
?>
]]>
       </programlisting>
       &example.outputs;
       <screen>
<![CDATA[
10
]]>
       </screen>
      </example>
     </para>
    </sect3>

   </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 array (0, 1, 2);
}
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">
<![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>   

  <sect2 xml:id="functions.returning-values.type-declaration">
   <title>Return type declarations</title>

   <para>
    PHP 7 adds support for return type declarations. Similarly to
    <link linkend="functions.arguments.type-declaration">argument type declarations</link>,
    return type declarations specify the type of the value that will be
    returned from a function. The same
    <link linkend="functions.arguments.type-declaration.types">types</link>
    are available for return type declarations as are available for argument
    type declarations.
   </para>

   <para>
    <link linkend="functions.arguments.type-declaration.strict">Strict typing</link>
    also has an effect on return type declarations. In the default weak mode,
    returned values will be coerced to the correct type if they are not
    already of that type. In strong mode, the returned value must be of the
    correct type, otherwise a <classname>TypeError</classname> will be thrown.
   </para>

   <note>
    <para>
     When overriding a parent method, the child's method must match any return
     type declaration on the parent. If the parent doesn't define a return
     type, then the child method may do so.
    </para>
   </note>

   <sect3 xml:id="functions.returning-values.type-declaration.examples">
    &reftitle.examples;

    <example>
     <title>Basic return type declaration</title>
     <programlisting role="php">
<![CDATA[
<?php
function sum($a, $b): float {
    return $a + $b;
}

// Note that a float will be returned.
var_dump(sum(1, 2));
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
float(3)
]]>
      </screen>
     </example>

     <example>
      <title>Strict mode in action</title>
      <programlisting role="php">
<![CDATA[
<?php
declare(strict_types=1);

function sum($a, $b): int {
    return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1, 2.5));
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
int(3)

Fatal error: Uncaught TypeError: Return value of sum() must be of the type integer, float returned in - on line 5 in -:5
Stack trace:
#0 -(9): sum(1, 2.5)
#1 {main}
  thrown in - on line 5
]]>
      </screen>
     </example>

     <example>
      <title>Returning an object</title>
      <programlisting role="php">
<![CDATA[
<?php
class C {}

function getC(): C {
    return new C;
}

var_dump(getC());
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
object(C)#1 (0) {
}
]]>
      </screen>
     </example>
    </sect3>
   </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()<br />\n";
}

function bar($arg = '')
{
    echo "In bar(); argument was '$arg'.<br />\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';
    }
}

echo Foo::$variable; // 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>
   </para>
   <para>
     As of PHP 5.4.0, you can call any <type>callable</type> stored in a variable.
    <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" as of PHP 7.0.0; prior, it raised a fatal error
?>
]]>
     </programlisting>
    </example>
   </para>
      
   <para>
    See also <function>is_callable</function>, <function>call_user_func</function>,
    <link linkend="language.variables.variable">
    variable variables</link> and <function>function_exists</function>.
   </para>
   
   <sect2 role="changelog">
    &reftitle.changelog;
    <para>
     <informaltable>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>&Version;</entry>
         <entry>&Description;</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>7.0.0</entry>
         <entry>
          'ClassName::methodName' is allowed as variable function.
         </entry>
        </row>
        <row>
         <entry>5.4.0</entry>
         <entry>
          Arrays, which are valid callables, are allowed as variable functions.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </para>
   </sect2>
  </sect1>
  
  <sect1 xml:id="functions.internal">
   <title>Internal (built-in) functions</title>
   
   <para>
    PHP comes standard with many functions and constructs. There are also
    functions that require specific PHP extensions compiled in, otherwise 
    fatal "undefined function" errors will appear. For example, to use 
    <link linkend="ref.image">image</link> functions such as 
    <function>imagecreatetruecolor</function>, PHP must be compiled with
    <productname>GD</productname> support. Or, to use
    <function>mysqli_connect</function>, PHP must be compiled with
    <link linkend="book.mysqli">MySQLi</link> support. There are many core functions
    that are included in every version of PHP, such as the
    <link linkend="ref.strings">string</link> and 
    <link linkend="ref.var">variable</link> functions. A call 
    to <function>phpinfo</function> or
    <function>get_loaded_extensions</function> will show which extensions are
    loaded into PHP. Also note that many extensions are enabled by default and
    that the PHP manual is split up by extension. See the
    <link linkend="configuration">configuration</link>,
    <link linkend="install">installation</link>, and individual
    extension chapters, for information on how to set up PHP.
   </para>
   <para>
    Reading and understanding a function's prototype is explained within the
    manual section titled <link linkend="about.prototypes">how to read a
    function definition</link>. It's important to realize what a function
    returns or if a function works directly on a passed in value. For example,
    <function>str_replace</function> will return the modified string while 
    <function>usort</function> works on the actual passed in variable
    itself. Each manual page also has specific information for each
    function like information on function parameters, behavior changes,
    return values for both success and failure, and availability information.
    Knowing these important (yet often subtle) differences is crucial for
    writing correct PHP code.
   </para>
   <note>
    <simpara>
     If the parameters given to a function are not what it expects, such as 
     passing an <type>array</type> where a <type>string</type> is expected, 
     the return value of the function is undefined. In this case it will
     likely return &null; but this is just a convention, and cannot be relied 
     upon.
    </simpara>
   </note>
   <para>
    See also <function>function_exists</function>, 
    <link linkend="funcref">the function reference</link>,
    <function>get_extension_funcs</function>, and 
    <function>dl</function>.
   </para>
  </sect1>
  
  <sect1 xml:id="functions.anonymous">
   <title>Anonymous functions</title>

   <simpara>
    Anonymous functions, also known as <literal>closures</literal>, allow the
    creation of functions which have no specified name. They are most useful as
    the value of <link linkend="language.types.callback">callback</link>
    parameters, but they have many other uses.
   </simpara>
   <simpara>
    Anonymous functions are implemented using the <link linkend="class.closure">
    <classname>Closure</classname></link> class.
   </simpara>

   <example>
    <title>Anonymous function example</title>
    <programlisting role="php">
<![CDATA[
<?php
echo preg_replace_callback('~-([a-z])~', function ($match) {
    return strtoupper($match[1]);
}, 'hello-world');
// outputs helloWorld
?>
]]>
    </programlisting>
   </example>

   <simpara>
    Closures can also be used as the values of variables; PHP automatically 
    converts such expressions into instances of the
    <classname>Closure</classname> internal class. Assigning a closure to a
    variable uses the same syntax as any other assignment, including the
    trailing semicolon:
   </simpara>

   <example>
    <title>Anonymous function variable assignment example</title>
    <programlisting role="php">
<![CDATA[
<?php
$greet = function($name)
{
    printf("Hello %s\r\n", $name);
};

$greet('World');
$greet('PHP');
?>
]]>
    </programlisting>
   </example>
   
   <simpara>
    Closures may also inherit variables from the parent scope. Any such
    variables must be passed to the <literal>use</literal> language construct.
    From PHP 7.1, these variables must not include &link.superglobals;,
    <varname>$this</varname>, or variables with the same name as a parameter.
   </simpara>

   <example>
    <title>Inheriting variables from the parent scope</title>
    <programlisting role="php">
<![CDATA[
<?php
$message = 'hello';

// No "use"
$example = function () {
    var_dump($message);
};
$example();

// Inherit $message
$example = function () use ($message) {
    var_dump($message);
};
$example();

// Inherited variable's value is from when the function
// is defined, not when called
$message = 'world';
$example();

// Reset message
$message = 'hello';

// Inherit by-reference
$example = function () use (&$message) {
    var_dump($message);
};
$example();

// The changed value in the parent scope
// is reflected inside the function call
$message = 'world';
$example();

// Closures can also accept regular arguments
$example = function ($arg) use ($message) {
    var_dump($arg . ' ' . $message);
};
$example("hello");
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Notice: Undefined variable: message in /example.php on line 6
NULL
string(5) "hello"
string(5) "hello"
string(5) "hello"
string(5) "world"
string(11) "hello world"
]]>
    </screen>
   </example>

   <simpara>
    Inheriting variables from the parent scope is <emphasis>not</emphasis> 
    the same as using global variables. 
    Global variables exist in the global scope, which is the same no
    matter what function is executing. The parent scope of a closure is the
    function in which the closure was declared (not necessarily the function it
    was called from). See the following example:
   </simpara>

   <example>
    <title>Closures and scoping</title>
    <programlisting role="php">
<![CDATA[
<?php
// A basic shopping cart which contains a list of added products
// and the quantity of each product. Includes a method which
// calculates the total price of the items in the cart using a
// closure as a callback.
class Cart
{
    const PRICE_BUTTER  = 1.00;
    const PRICE_MILK    = 3.00;
    const PRICE_EGGS    = 6.95;

    protected $products = array();
    
    public function add($product, $quantity)
    {
        $this->products[$product] = $quantity;
    }
    
    public function getQuantity($product)
    {
        return isset($this->products[$product]) ? $this->products[$product] :
               FALSE;
    }
    
    public function getTotal($tax)
    {
        $total = 0.00;
        
        $callback =
            function ($quantity, $product) use ($tax, &$total)
            {
                $pricePerItem = constant(__CLASS__ . "::PRICE_" .
                    strtoupper($product));
                $total += ($pricePerItem * $quantity) * ($tax + 1.0);
            };
        
        array_walk($this->products, $callback);
        return round($total, 2);
    }
}

$my_cart = new Cart;

// Add some items to the cart
$my_cart->add('butter', 1);
$my_cart->add('milk', 3);
$my_cart->add('eggs', 6);

// Print the total with a 5% sales tax.
print $my_cart->getTotal(0.05) . "\n";
// The result is 54.29
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Automatic binding of <literal>$this</literal></title>
    <programlisting role="php">
<![CDATA[
<?php

class Test
{
    public function testing()
    {
        return function() {
            var_dump($this);
        };
    }
}

$object = new Test;
$function = $object->testing();
$function();
    
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
object(Test)#1 (0) {
}
]]>
    </screen>
    &example.outputs.53;
    <screen>
<![CDATA[
Notice: Undefined variable: this in script.php on line 8
NULL]]>
    </screen>
   </example>

   <para>
    As of PHP 5.4.0, when declared in the context of a class, the current class is
    automatically bound to it, making <literal>$this</literal> available
    inside of the function's scope. If this automatic binding of the current
    class is not wanted, then
    <link linkend="functions.anonymous-functions.static">static anonymous
    functions</link> may be used instead.
   </para>

   <sect2 xml:id="functions.anonymous-functions.static">
    <title>Static anonymous functions</title>
    <para>
     As of PHP 5.4, anonymous functions may be declared statically. This
     prevents them from having the current class automatically bound to
     them. Objects may also not be bound to them at runtime.
    </para>
    <para>
     <example>
      <title>Attempting to use <literal>$this</literal> inside a static anonymous function</title>
      <programlisting role="php">
<![CDATA[
<?php

class Foo
{
    function __construct()
    {
        $func = static function() {
            var_dump($this);
        };
        $func();
    }
};
new Foo();

?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Notice: Undefined variable: this in %s on line %d
NULL
]]>
      </screen>
     </example>
    </para>

    <para>
     <example>
      <title>Attempting to bind an object to a static anonymous function</title>
      <programlisting role="php">
<![CDATA[
<?php

$func = static function() {
    // function body
};
$func = $func->bindTo(new StdClass);
$func();

?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Warning: Cannot bind an instance to a static closure in %s on line %d
]]>
      </screen>
     </example>
    </para>
   </sect2>
   
   <sect2 role="changelog">
    &reftitle.changelog;
    <para>
     <informaltable>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>&Version;</entry>
         <entry>&Description;</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>7.1.0</entry>
         <entry>
          Anonymous functions may not close over &link.superglobals;,
          <varname>$this</varname>, or any variable with the same name as a
          parameter.
         </entry>
        </row>
        <row>
         <entry>5.4.0</entry>
         <entry>
          Anonymous functions may use <varname>$this</varname>, as well as be
          declared statically.
         </entry>
        </row>
        <row>
         <entry>5.3.0</entry>
         <entry>
          Anonymous functions become available.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </informaltable>
    </para>
   </sect2>

   <sect2 role="notes">
    &reftitle.notes;
    <note>
     <simpara>
      It is possible to use <function>func_num_args</function>,
      <function>func_get_arg</function>, and <function>func_get_args</function>
      from within a closure.
     </simpara>
    </note>
   </sect2>

  </sect1>

 </chapter>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->