<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.63 $ -->
 <chapter id="language.functions">
  <title>Functions</title>

  <sect1 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="keyword.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>
    In PHP 3, functions must be defined before they are referenced. No
    such requirement exists since PHP 4. <emphasis>Except</emphasis> when
    a function is conditionally defined such 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 processesing 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>
    PHP 3 does not support variable numbers of arguments to functions,
    although default arguments are supported (see <link
    linkend="functions.arguments.default">Default argument
    values</link> for more information). Both are supported, as of PHP 4: see <link
    linkend="functions.variable-arg-list">Variable-length argument
    lists</link> and 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. However avoid recursive
    function/method calls with over 100-200 recursion levels as it can smash
    the stack and cause a termination of the current script.
    <example>
     <title>Recursive functions</title>
     <programlisting role="php">
<![CDATA[
<?php
function recursion($a)
{
    if ($a < 20) {
        echo "$a\n";
        recursion($a + 1);
    }
}
?>
]]>
     </programlisting>
    </example>
   </para>

  </sect1>
 
  <sect1 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.
   </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>. Variable-length argument lists are supported only
    in PHP 4 and later; see <link
    linkend="functions.variable-arg-list">Variable-length argument
    lists</link> and the function references for
    <function>func_num_args</function>,
    <function>func_get_arg</function>, and
    <function>func_get_args</function> for more information. A
    similar effect can be achieved in PHP 3 by passing an array of
    arguments to a function:
   </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 id="functions.arguments.by-reference">
    <title>Making arguments be passed by reference</title>
 
    <simpara>
     By default, function arguments are passed by value (so that if
     you change the value of the argument within the function, it does
     not get changed outside of the function). If you wish to allow a
     function to modify its arguments, you must pass them by
     reference.
    </simpara>
    <para>
     If you want an argument to a function to always be passed by
     reference, you can 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 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("espresso");
?>
]]>
      </programlisting>
     </example>
    </para>
 
    <para>
     The output from the above snippet is:
    </para>
    <para>
     <screen>
Making a cup of cappuccino.
Making a cup of espresso.
     </screen>
    </para>
    <para>
     Also PHP allows you to use arrays and 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>
    </para>
 
    <para>
     The output of the above example is:
    </para>
    <para>
     <screen>
Warning: Missing argument 2 in call to makeyogurt() in 
/usr/local/etc/httpd/htdocs/php3test/functest.html on line 41
Making a bowl of raspberry .
     </screen>
    </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>
    </para>
 
    <para>
     The output of this example is:
    </para>
    <para>
     <screen>
Making a bowl of acidophilus raspberry.
     </screen>
    </para>
    
    <note>
     <simpara>
      As of PHP 5, default values may be passed by reference.      
     </simpara>
    </note>

   </sect2>

   <sect2 id="functions.variable-arg-list">
    <title>Variable-length argument lists</title>

    <simpara>
     PHP 4 and above has support for variable-length argument lists in
     user-defined functions. This is really quite easy, using the
     <function>func_num_args</function>,
     <function>func_get_arg</function>, and
     <function>func_get_args</function> functions.
    </simpara>

    <simpara>
     No special syntax is required, and argument lists may still be
     explicitly provided with function definitions and will behave as
     normal.
    </simpara>

   </sect2>

  </sect1>
 
  <sect1 id="functions.returning-values">
   <title>Returning values</title>
 
   <para>
    Values are returned by using the optional return statement. Any
    type may be returned, including lists 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>
   <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>
    You can't return multiple values from a function, but similar
    results can be obtained by returning a list.
   </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, you have to 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>
  </sect1>
 
  <sect1 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. You need to use
    your own wrapper function to utilize 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>
    You can also call an object's method by using the variable functions
    feature.
    <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>
    See also <function>call_user_func</function>,
    <link linkend="language.variables.variable">
    variable variables</link> and <function>function_exists</function>.
   </para>
  </sect1>
  
  <sect1 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 
    you'll get fatal "undefined function" errors.  For example, to use 
    <link linkend="ref.image">image</link> functions such as 
    <function>imagecreatetruecolor</function>, you'll need your PHP compiled
    with <productname>GD</productname> support.  Or, to use <function>mysql_connect</function> you'll
    need your PHP compiled in with <link linkend="ref.mysql">MySQL</link>
    support.  There are many core functions that are included in every
    version of PHP like 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 you which
    extensions are loaded into your 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 setup your 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>

 </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:"../../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
-->