<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.28 $ -->
 <reference id="ref.funchand">
  <title>Function Handling functions</title>
  <titleabbrev>Functions</titleabbrev>

  <partintro>
   <para>
    These functions all handle various operations involved in working
    with functions.
   </para>
  </partintro>
   
  <refentry id="function.call-user-func-array">
   <refnamediv>
    <refname>call_user_func_array</refname>
    <refpurpose>
     Call a user function given with an array of parameters
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>call_user_func_array</methodname>
      <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
      <methodparam choice="opt"><type>array</type><parameter>paramarr</parameter></methodparam>
     </methodsynopsis>
    <para>
     Call a user defined function given by
     <parameter>function_name</parameter>, with
     the parameters in <parameter>paramarr</parameter>.
     For example:
     <informalexample>
      <programlisting role="php">
<![CDATA[
function debug($var, $val)
    echo "***DEBUGGING\nVARIABLE: $var\nVALUE:";
    if (is_array($val) || is_object($val) || is_resource($val))
        print_r($val);
    else
        echo "\n$val\n";
    echo "***\n";
}

$c = mysql_connect();
$host = $HTTP_SERVER_VARS["SERVER_NAME"];

call_user_func_array ('debug', array("host", $host));
call_user_func_array ('debug', array("c", $c));
call_user_func_array ('debug', array("HTTP_POST_VARS", $HTTP_POST_VARS));
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     See also:
     <function>call_user_func</function>,
     <function>call_user_method</function>,
     <function>call_user_method_array</function>.
    </para>
    <note>
     <para>
      This function was added to the CVS code after release of PHP 4.0.4pl1
     </para>
    </note>
   </refsect1>
  </refentry>
  
  <refentry id="function.call-user-func">
   <refnamediv>
    <refname>call_user_func</refname>
    <refpurpose>
     Call a user function given by the first parameter
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>call_user_func</methodname>
      <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>parameter</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
     </methodsynopsis>
    <para>
     Call a user defined function given by the
     <parameter>function_name</parameter> parameter.  Take the
     following:
     <informalexample>
      <programlisting role="php">
<![CDATA[
function barber ($type) {
    print "You wanted a $type haircut, no problem";
}
call_user_func ('barber', "mushroom");
call_user_func ('barber', "shave");
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     See also:
     <function>call_user_func_array</function>,
     <function>call_user_method</function>,
     <function>call_user_method_array</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.create-function">
   <refnamediv>
    <refname>create_function</refname>
    <refpurpose>Create an anonymous (lambda-style) function</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>create_function</methodname>
      <methodparam><type>string</type><parameter>args</parameter></methodparam>
      <methodparam><type>string</type><parameter>code</parameter></methodparam>
     </methodsynopsis>
    <para>
     Creates an anonymous function from the parameters passed, and
     returns a unique name for it. Usually the
     <parameter>args</parameter> will be passed as a single quote
     delimited string, and this is also recommended for the
     <parameter>code</parameter>. The reason for using single quoted
     strings, is to protect
     the variable names from parsing, otherwise, if you use double
     quotes there will be a need to escape the variable names, e.g. 
     <literal>\$avar</literal>.
    </para>
    <para>
     You can use this function, to (for example) create a function
     from information gathered at run time:
     <example>
      <title>
       Creating an anonymous function with <function>create_function</function>
      </title>
      <programlisting role="php">
<![CDATA[
$newfunc = create_function('$a,$b','return "ln($a) + ln($b) = ".log($a * $b);');
echo "New anonymous function: $newfunc\n";
echo $newfunc(2,M_E)."\n";
// outputs
// New anonymous function: lambda_1
// ln(2) + ln(2.718281828459) = 1.6931471805599
]]>
      </programlisting>
     </example>
     Or, perhaps to have general handler function that can apply a set
     of operations to a list of parameters:
     <example>
      <title>
       Making a general processing function with
       <function>create_function</function>
      </title>
      <programlisting role="php">
<![CDATA[
function process($var1, $var2, $farr) {
    for ($f=0; $f < count($farr); $f++)
    echo $farr[$f]($var1,$var2)."\n";
}

// create a bunch of math functions
$f1 = 'if ($a >=0) {return "b*a^2 = ".$b*sqrt($a);} else {return false;}';
$f2 = "return \"min(b^2+a, a^2,b) = \".min(\$a*\$a+\$b,\$b*\$b+\$a);";
$f3 = 'if ($a > 0 && $b != 0) {return "ln(a)/b = ".log($a)/$b; } else { return false; }';
$farr = array(
    create_function('$x,$y', 'return "some trig: ".(sin($x) + $x*cos($y));'),
    create_function('$x,$y', 'return "a hypotenuse: ".sqrt($x*$x + $y*$y);'),
    create_function('$a,$b', $f1),
    create_function('$a,$b', $f2),
    create_function('$a,$b', $f3)
    );

echo "\nUsing the first array of anonymous functions\n";
echo "parameters: 2.3445, M_PI\n";
process(2.3445, M_PI, $farr);

// now make a bunch of string processing functions
$garr = array(
    create_function('$b,$a','if (strncmp($a,$b,3) == 0) return "** \"$a\" '.
    'and \"$b\"\n** Look the same to me! (looking at the first 3 chars)";'),
    create_function('$a,$b','; return "CRCs: ".crc32($a)." , ".crc32(b);'),
    create_function('$a,$b','; return "similar(a,b) = ".similar_text($a,$b,&$p)."($p%)";')
    );
echo "\nUsing the second array of anonymous functions\n";
process("Twas brilling and the slithy toves", "Twas the night", $garr);
]]>
      </programlisting>
     </example>
     and when you run the code above, the output will be:
     <informalexample>
      <programlisting>
<![CDATA[
Using the first array of anonymous functions
parameters: 2.3445, M_PI
some trig: -1.6291725057799
a hypotenuse: 3.9199852871011
b*a^2 = 4.8103313314525
min(b^2+a, a^2,b) = 8.6382729035898
ln(a/b) = 0.27122299212594

Using the second array of anonymous functions
** "Twas the night" and "Twas brilling and the slithy toves"
** Look the same to me! (looking at the first 3 chars)
CRCs: -725381282 , 1908338681
similar(a,b) = 11(45.833333333333%)
]]>
      </programlisting>
     </informalexample>
    But perhaps the most common use for of lambda-style (anonymous) functions
    is to create callback functions, for example when using
    <function>array_walk</function> or <function>usort</function>
    <example>
     <title>Using anonymous functions as callback functions</title>
     <programlisting role="php">
<![CDATA[
$av = array("the ","a ","that ","this ");
array_walk($av, create_function('&$v,$k','$v = $v."mango";'));
print_r($av);  // for PHP 3 use var_dump()
// outputs:
// Array
// (
//   [0] => the mango
//   [1] => a mango
//   [2] => that mango
//   [3] => this mango
// )

// an array of strings ordered from shorter to longer
$sv = array("small","larger","a big string","it is a string thing");
print_r($sv);
// outputs:
// Array
// (
//   [0] => small
//   [1] => larger
//   [2] => a big string
//   [3] => it is a string thing
// )

// sort it from longer to shorter
usort($sv, create_function('$a,$b','return strlen($b) - strlen($a);'));
print_r($sv);
// outputs:
// Array
// (
//   [0] => it is a string thing
//   [1] => a big string
//   [2] => larger
//   [3] => small
// )
]]>
     </programlisting>
    </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.func-get-arg">
   <refnamediv>
    <refname>func_get_arg</refname>
    <refpurpose>Return an item from the argument list</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>func_get_arg</methodname>
      <methodparam><type>int</type><parameter>arg_num</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Returns the argument which is at the
     <parameter>arg_num</parameter>'th offset into a user-defined
     function's argument list. Function arguments are counted starting
     from zero. <function>func_get_arg</function> will generate a
     warning if called from outside of a function definition.
    </simpara>
    <simpara>
     If <parameter>arg_num</parameter> is greater than the number of
     arguments actually passed, a warning will be generated and
     <function>func_get_arg</function> will return &false;.
    </simpara>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
function foo() {
     $numargs = func_num_args();
     echo "Number of arguments: $numargs<br>\n";
     if ($numargs >= 2) {
     echo "Second argument is: " . func_get_arg (1) . "<br>\n";
     }
} 

foo (1, 2, 3);
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     <function>func_get_arg</function> may be used in conjunction with
     <function>func_num_args</function> and
     <function>func_get_args</function> to allow user-defined
     functions to accept variable-length argument lists.
    </simpara>
    <note>
     <simpara>
      This function was added in PHP 4.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.func-get-args">
   <refnamediv>
    <refname>func_get_args</refname>
    <refpurpose>
     Returns an array comprising a function's argument list
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>func_get_args</methodname>
      <void/>
     </methodsynopsis>
    <simpara>
     Returns an array in which each element is the corresponding
     member of the current user-defined function's argument
     list. <function>func_get_args</function> will generate a warning
     if called from outside of a function definition.
    </simpara>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
function foo() {
    $numargs = func_num_args();
    echo "Number of arguments: $numargs<br>\n";
    if ($numargs >= 2) {
    echo "Second argument is: " . func_get_arg (1) . "<br>\n";
    }
    $arg_list = func_get_args();
    for ($i = 0; $i < $numargs; $i++) {
    echo "Argument $i is: " . $arg_list[$i] . "<br>\n";
    }
} 

foo (1, 2, 3);
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     <function>func_get_args</function> may be used in conjunction
     with <function>func_num_args</function> and
     <function>func_get_arg</function> to allow user-defined functions
     to accept variable-length argument lists.
    </simpara>
    <note>
     <simpara>
      This function was added in PHP 4.
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.func-num-args">
   <refnamediv>
    <refname>func_num_args</refname>
    <refpurpose>
     Returns the number of arguments passed to the function
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>func_num_args</methodname>
      <void/>
     </methodsynopsis>
    <simpara>
     Returns the number of arguments passed into the current
     user-defined function. <function>func_num_args</function> will
     generate a warning if called from outside of a user-defined function.
    </simpara>
    <para>
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
function foo() {
    $numargs = func_num_args();
    echo "Number of arguments: $numargs\n";
} 

foo (1, 2, 3);    // Prints 'Number of arguments: 3'
?>
]]>
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     <function>func_num_args</function> may be used in conjunction
     with <function>func_get_arg</function> and
     <function>func_get_args</function> to allow user-defined
     functions to accept variable-length argument lists.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.function-exists">
   <refnamediv>
    <refname>function_exists</refname>
    <refpurpose>
     Return &true; if the given function has been defined
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>function_exists</methodname>
      <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
     </methodsynopsis>
    <para>
     Checks the list of defined functions for
     <parameter>function_name</parameter>.    Returns &true; if the given
     function name was found, &false; otherwise.
     <informalexample>
      <programlisting role="php">
<![CDATA[
if (function_exists('imap_open')) {
    echo "IMAP functions are available.<br>\n";
} else {
    echo "IMAP functions are not available.<br>\n";
}
]]>
      </programlisting>
     </informalexample>
     Note that a function name may exist, even if the function itself
     is unusable due to configuration or compiling options. 
    </para>
    <para>
     See also <function>method_exists</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.get-defined-functions">
   <refnamediv>
    <refname>get_defined_functions</refname>
    <refpurpose>
     Returns an array of all defined functions
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>array</type><methodname>get_defined_functions</methodname>
      <void/>
     </methodsynopsis>
    <para>
     This function returns an multidimensional array containing a list of
     all defined functions, both built-in (internal) and user-defined. The 
     internal functions will be accessible via
     <varname>$arr["internal"]</varname>, and the user defined ones using
     <varname>$arr["user"]</varname> (see example below).
     <informalexample>
      <programlisting role="php">
<![CDATA[
function myrow($id, $data) {
    return "<tr><th>$id</th><td>$data</td></tr>\n";
}

$arr = get_defined_functions();

print_r($arr);
]]>
     </programlisting>
     </informalexample>
    </para>
    <para>
     Will output something along the lines of:
     <informalexample>
      <programlisting>
<![CDATA[
Array
(
    [internal] => Array
        (
            [0] => zend_version
            [1] => func_num_args
            [2] => func_get_arg
            [3] => func_get_args
            [4] => strlen
            [5] => strcmp
            [6] => strncmp
            ...
            [750] => bcscale
            [751] => bccomp
        )

    [user] => Array
        (
            [0] => myrow
        )

)
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     See also <function>get_defined_vars</function> and 
     <function>get_defined_constants</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.register-shutdown-function">
   <refnamediv>
    <refname>register_shutdown_function</refname>
    <refpurpose>
     Register a function for execution on shutdown
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>register_shutdown_function</methodname>
      <methodparam><type>string</type><parameter>func</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Registers the function named by <parameter>func</parameter> to be
     executed when script processing is complete.
    </simpara>
    <para>
     Multiple calls to <function>register_shutdown_function</function> can be
     made, and each will be called in the same order as they were registered.
     If you call <function>exit</function> within one registered shutdown
     function, processing will stop completely and no other registered
     shutdown functions will be called.
    </para>
    <para>
     The registered shutdown functions are called after the request has been
     completed (including sending any output buffers), so it is not possible
     to send output to the browser using <function>echo</function> or
     <function>print</function>, or retrieve the contents of any output
     buffers using <function>ob_get_contents</function>.
    </para>
    &note.func-callback;
   </refsect1>
  </refentry>
  
  <refentry id="function.register-tick-function">
   <refnamediv>
    <refname>register_tick_function</refname>
    <refpurpose>
     Register a function for execution on each tick
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>register_tick_function</methodname>
      <methodparam><type>string</type><parameter>func</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     Registers the function named by <parameter>func</parameter> to be
     executed when a <link
     linkend="control-structures.declare">tick</link> is
     called.</simpara>
   </refsect1>
  </refentry>
  
  <refentry id="function.unregister-tick-function">
   <refnamediv>
    <refname>unregister_tick_function</refname>
    <refpurpose>
     De-register a function for execution on each tick
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>void</type><methodname>unregister_tick_function</methodname>
      <methodparam><type>string</type><parameter>func</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     De-registers the function named by <parameter>func</parameter> so it is
     no longer executed when a <link
     linkend="control-structures.declare">tick</link> is
     called.</simpara>
   </refsect1>
  </refentry>
  
 </reference>

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