php-doc-en/language/functions.sgml

  <chapter id="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:
 
     <informalexample>
      <programlisting>
function foo ($arg_1, $arg_2, ..., $arg_n) {
    echo "Example function.\n";
    return $retval;
}
      </programlisting>
     </informalexample>
     
    <simpara>
     Any valid PHP code may appear inside a function, even other
     functions and <link linkend="keyword.class">class</link>
     definitions.
     
    <simpara>
     Functions must be defined before they are referenced.
 
   <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.
 
     <informalexample>
      <programlisting>
function square ($num) {
    return $num * $num;
}
echo square (4);   // outputs '16'.
      </programlisting>
     </informalexample>
      
    <para>
     You can't return multiple values from a function, but similar
     results can be obtained by returning a list.
 
     <informalexample>
      <programlisting>
function small_numbers() {
   return array (0, 1, 2);
}
list ($zero, $one, $two) = small_numbers();
      </programlisting>
     </informalexample>
 
   <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 variables and/or constants.
 
    <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 not supported,
     but a similar effect may be obtained by passing arrays.
 
     <informalexample>
      <programlisting>
function takes_array($input) {
    echo "$input[0] + $input[1] = ", $input[0]+$input[1];
}
      </programlisting>
     </informalexample>
 
    <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.
       
     <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:
 
      <informalexample>
       <programlisting>
function add_some_extra(&amp;$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>
      </informalexample>
 
     <para>
      If you wish to pass a variable by reference to a function which
      does not do this by default, you may prepend an ampersand to the 
      argument name in the function call:
 
      <informalexample>
       <programlisting>
function foo ($bar) {
    $bar .= ' and something extra.';
}
$str = 'This is a string, ';
foo ($str);
echo $str;    // outputs 'This is a string, '
foo (&amp;$str);
echo $str;    // outputs 'This is a string, and something extra.'
       </programlisting>
      </informalexample>
 
    <sect2 id="functions.arguments.default">
     <title>Default argument values</title>
 
     <para>
      A function may define C++-style default values for scalar
      arguments as follows:
 
      <informalexample>
       <programlisting>
function makecoffee ($type = "cappucino") {
    return "Making a cup of $type.\n";
}
echo makecoffee ();
echo makecoffee ("espresso");
       </programlisting>
      </informalexample>
 
     <para>
      The output from the above snippet is:
 
      <screen>
Making a cup of cappucino.
Making a cup of espresso.
      </screen>
 
     <simpara>
      The default value must be a constant expression, not (for
      example) a variable or class member.

     <para>
     In PHP 4.0 it's also possible to specify <literal>unset</literal>
     for default argument.  This means that the argument will not be
     set at all, if a value is not supplied.
 
     <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:
 
      <informalexample>
       <programlisting>
function makeyogurt ($type = "acidophilus", $flavour) {
    return "Making a bowl of $type $flavour.\n";
}
 
echo makeyogurt ("raspberry");   // won't work as expected
       </programlisting>
      </informalexample>
 
     <para>
      The output of the above example is:
 
      <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>
      Now, compare the above with this:
 
      <informalexample>
       <programlisting>
function makeyogurt ($flavour, $type = "acidophilus") {
    return "Making a bowl of $type $flavour.\n";
}
 
echo makeyogurt ("raspberry");   // works as expected
       </programlisting>
      </informalexample>
 
     <para>
      The output of this example is:
 
      <screen>
Making a bowl of acidophilus raspberry.
     </screen>
 
   <sect1 id="functions.old-syntax">
    <title><literal>old_function</literal></title>
 
    <simpara>
     The <literal>old_function</literal> statement allows you to declare
     a function using a syntax identical to PHP/FI2 (except you must
     replace 'function' with 'old_function'.
    <simpara>
     This is a deprecated feature, and should only be used by the
     PHP/FI2->PHP3 convertor.
    <warning>
     <para>
      Functions declared as <literal>old_function</literal>
      cannot be called from PHP's internal code. Among other
      things, this means you can't use them in functions such as
      <function>usort</function>, <function>array_walk</function>, and
      <function>register_shutdown_function</function>. You can get around
      this limitation by writing a wrapper function (in normal PHP3 form)
      to call the <literal>old_function</literal>.
     </para>
    </warning>
 
  </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
 sgml-parent-document:nil
 sgml-default-dtd-file:"../manual.ced"
 sgml-exposed-tags:nil
 sgml-local-catalogs:nil
 sgml-local-ecat-files:nil
 End:
 -->