mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-17 01:18:55 +00:00
a79ab53063
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@115063 c90b9560-bf6c-de11-be94-00142212c4b1
506 lines
12 KiB
XML
506 lines
12 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.33 $ -->
|
|
<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 role="php">
|
|
<![CDATA[
|
|
function foo ($arg_1, $arg_2, ..., $arg_n)
|
|
{
|
|
echo "Example function.\n";
|
|
return $retval;
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<!--
|
|
|
|
status of func(const $param) ?
|
|
zend doesn't care at all whether or not you specify it.
|
|
I've never seen it before... what's its use? (or was...)
|
|
|
|
-->
|
|
|
|
<simpara>
|
|
Any valid PHP code may appear inside a function, even other
|
|
functions and <link linkend="keyword.class">class</link>
|
|
definitions.
|
|
</simpara>
|
|
<simpara>
|
|
In PHP 3, functions must be defined before they are referenced. No
|
|
such requirement exists in 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.
|
|
<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>
|
|
<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 accessable. */
|
|
|
|
bar();
|
|
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<simpara>
|
|
PHP does not support function overloading, nor is it possible to
|
|
undefine or redefine previously-declared functions.
|
|
</simpara>
|
|
<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). PHP 4 supports both: 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>
|
|
|
|
</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 variables and/or constants.
|
|
</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:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function takes_array($input)
|
|
{
|
|
echo "$input[0] + $input[1] = ", $input[0]+$input[1];
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</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 (&) to the argument
|
|
name in the function definition:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
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>
|
|
</informalexample>
|
|
</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:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function makecoffee ($type = "cappuccino")
|
|
{
|
|
return "Making a cup of $type.\n";
|
|
}
|
|
echo makecoffee ();
|
|
echo makecoffee ("espresso");
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
The output from the above snippet is:
|
|
|
|
<screen>
|
|
Making a cup of cappuccino.
|
|
Making a cup of espresso.
|
|
</screen>
|
|
</para>
|
|
|
|
<simpara>
|
|
The default value must be a constant expression, not (for
|
|
example) a variable or class member.
|
|
</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:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function makeyogurt ($type = "acidophilus", $flavour)
|
|
{
|
|
return "Making a bowl of $type $flavour.\n";
|
|
}
|
|
|
|
echo makeyogurt ("raspberry"); // won't work as expected
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<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>
|
|
|
|
<para>
|
|
Now, compare the above with this:
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function makeyogurt ($flavour, $type = "acidophilus")
|
|
{
|
|
return "Making a bowl of $type $flavour.\n";
|
|
}
|
|
|
|
echo makeyogurt ("raspberry"); // works as expected
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
The output of this example is:
|
|
|
|
<screen>
|
|
Making a bowl of acidophilus raspberry.
|
|
</screen>
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="functions.variable-arg-list">
|
|
<title>Variable-length argument lists</title>
|
|
|
|
<simpara>
|
|
PHP 4 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.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function square ($num)
|
|
{
|
|
return $num * $num;
|
|
}
|
|
echo square (4); // outputs '16'.
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
You can't return multiple values from a function, but similar
|
|
results can be obtained by returning a list.
|
|
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function small_numbers()
|
|
{
|
|
return array (0, 1, 2);
|
|
}
|
|
list ($zero, $one, $two) = small_numbers();
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
To return a reference from a function, you have to use
|
|
the reference operator & in both the function declaration and
|
|
when assigning the returned value to a variable:
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
function &returns_reference()
|
|
{
|
|
return $someref;
|
|
}
|
|
|
|
$newref =& returns_reference();
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<simpara>
|
|
For more information on references, please check out <link
|
|
linkend="language.references">References Explained</link>.
|
|
</simpara>
|
|
</sect1>
|
|
|
|
<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>
|
|
<simpara>
|
|
This is a deprecated feature, and should only be used by the
|
|
PHP/FI2->PHP 3 convertor.
|
|
</simpara>
|
|
<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
|
|
PHP 3 form) to call the <literal>old_function</literal>.
|
|
</para>
|
|
</warning>
|
|
|
|
</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 Var()
|
|
{
|
|
$name = 'Bar';
|
|
$this->$name(); // This calls the Bar() method
|
|
}
|
|
|
|
function Bar()
|
|
{
|
|
echo "This is Bar";
|
|
}
|
|
}
|
|
|
|
$foo = new Foo();
|
|
$funcname = "Var";
|
|
$foo->$funcname(); // This calls $foo->Var()
|
|
|
|
?>
|
|
]]>
|
|
</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>
|
|
</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
|
|
-->
|