Source of: /manual/en/functions.arguments.php
<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/language.functions.inc";
$setup = array (
'home' =>
array (
0 => 'index.php',
1 => 'PHP Manual',
),
'head' =>
array (
0 => 'UTF-8',
1 => 'en',
),
'this' =>
array (
0 => 'functions.arguments.php',
1 => 'Function arguments',
),
'up' =>
array (
0 => 'language.functions.php',
1 => 'Functions',
),
'prev' =>
array (
0 => 'functions.user-defined.php',
1 => 'User-defined functions',
),
'next' =>
array (
0 => 'functions.returning-values.php',
1 => 'Returning values',
),
);
$setup["toc"] = $TOC;
$setup["parents"] = $PARENTS;
manual_setup($setup);
manual_header();
?>
<div id="functions.arguments" class="sect1">
<h2 class="title">Function arguments</h2>
<p class="simpara">
Information may be passed to functions via the argument list,
which is a comma-delimited list of expressions.
</p>
<p class="para">
PHP supports passing arguments by value (the default), <a href="functions.arguments.php#functions.arguments.by-reference" class="link">passing by
reference</a>, and <a href="functions.arguments.php#functions.arguments.default" class="link">default argument
values</a>. <a href="functions.arguments.php#functions.variable-arg-list" class="link">Variable-length
argument lists</a> are also supported, see also the function references for
<a href="function.func-num-args.php" class="function">func_num_args()</a>,
<a href="function.func-get-arg.php" class="function">func_get_arg()</a>, and
<a href="function.func-get-args.php" class="function">func_get_args()</a> for more information.
</p>
<p class="para">
</p><div class="example">
<p><b>Example #1 Passing arrays to functions</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">takes_array</span><span style="color: #007700">(</span><span style="color: #0000BB">$input</span><span style="color: #007700">)<br />{<br /> echo </span><span style="color: #DD0000">"</span><span style="color: #0000BB">$input</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]</span><span style="color: #DD0000"> + </span><span style="color: #0000BB">$input</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">]</span><span style="color: #DD0000"> = "</span><span style="color: #007700">, </span><span style="color: #0000BB">$input</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">]+</span><span style="color: #0000BB">$input</span><span style="color: #007700">[</span><span style="color: #0000BB">1</span><span style="color: #007700">];<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<div id="functions.arguments.by-reference" class="sect2">
<h3 class="title">Making arguments be passed by reference</h3>
<p class="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.
</p>
<p class="para">
To have an argument to a function always passed by reference, prepend an
ampersand (&) to the argument name in the function definition:
</p>
<p class="para">
</p><div class="example">
<p><b>Example #2 Passing function parameters by reference</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">add_some_extra</span><span style="color: #007700">(&</span><span style="color: #0000BB">$string</span><span style="color: #007700">)<br />{<br /> </span><span style="color: #0000BB">$string </span><span style="color: #007700">.= </span><span style="color: #DD0000">'and something extra.'</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">$str </span><span style="color: #007700">= </span><span style="color: #DD0000">'This is a string, '</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">add_some_extra</span><span style="color: #007700">(</span><span style="color: #0000BB">$str</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">$str</span><span style="color: #007700">; </span><span style="color: #FF8000">// outputs 'This is a string, and something extra.'<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
</div>
<div id="functions.arguments.default" class="sect2">
<h3 class="title">Default argument values</h3>
<p class="para">
A function may define C++-style default values for scalar
arguments as follows:
</p>
<p class="para">
</p><div class="example">
<p><b>Example #3 Use of default parameters in functions</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">makecoffee</span><span style="color: #007700">(</span><span style="color: #0000BB">$type </span><span style="color: #007700">= </span><span style="color: #DD0000">"cappuccino"</span><span style="color: #007700">)<br />{<br /> return </span><span style="color: #DD0000">"Making a cup of </span><span style="color: #0000BB">$type</span><span style="color: #DD0000">.\n"</span><span style="color: #007700">;<br />}<br />echo </span><span style="color: #0000BB">makecoffee</span><span style="color: #007700">();<br />echo </span><span style="color: #0000BB">makecoffee</span><span style="color: #007700">(</span><span style="color: #0000BB">null</span><span style="color: #007700">);<br />echo </span><span style="color: #0000BB">makecoffee</span><span style="color: #007700">(</span><span style="color: #DD0000">"espresso"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<p class="para">
The output from the above snippet is:
</p>
<p class="para">
<div class="example-contents screen"><br />
Making a cup of cappuccino.<br />
Making a cup of .<br />
Making a cup of espresso.<br />
</div>
</p>
<p class="para">
PHP also allows the use of <a href="language.types.array.php" class="type array">array</a>s and the special type <b><tt class="constant">NULL</tt></b>
as default values, for example:
</p>
<p class="para">
</p><div class="example">
<p><b>Example #4 Using non-scalar types as default values</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">makecoffee</span><span style="color: #007700">(</span><span style="color: #0000BB">$types </span><span style="color: #007700">= array(</span><span style="color: #DD0000">"cappuccino"</span><span style="color: #007700">), </span><span style="color: #0000BB">$coffeeMaker </span><span style="color: #007700">= </span><span style="color: #0000BB">NULL</span><span style="color: #007700">)<br />{<br /> </span><span style="color: #0000BB">$device </span><span style="color: #007700">= </span><span style="color: #0000BB">is_null</span><span style="color: #007700">(</span><span style="color: #0000BB">$coffeeMaker</span><span style="color: #007700">) ? </span><span style="color: #DD0000">"hands" </span><span style="color: #007700">: </span><span style="color: #0000BB">$coffeeMaker</span><span style="color: #007700">;<br /> return </span><span style="color: #DD0000">"Making a cup of "</span><span style="color: #007700">.</span><span style="color: #0000BB">join</span><span style="color: #007700">(</span><span style="color: #DD0000">", "</span><span style="color: #007700">, </span><span style="color: #0000BB">$types</span><span style="color: #007700">).</span><span style="color: #DD0000">" with </span><span style="color: #0000BB">$device</span><span style="color: #DD0000">.\n"</span><span style="color: #007700">;<br />}<br />echo </span><span style="color: #0000BB">makecoffee</span><span style="color: #007700">();<br />echo </span><span style="color: #0000BB">makecoffee</span><span style="color: #007700">(array(</span><span style="color: #DD0000">"cappuccino"</span><span style="color: #007700">, </span><span style="color: #DD0000">"lavazza"</span><span style="color: #007700">), </span><span style="color: #DD0000">"teapot"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<p class="simpara">
The default value must be a constant expression, not (for
example) a variable, a class member or a function call.
</p>
<p class="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:
</p>
<p class="para">
</p><div class="example">
<p><b>Example #5 Incorrect usage of default function arguments</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">makeyogurt</span><span style="color: #007700">(</span><span style="color: #0000BB">$type </span><span style="color: #007700">= </span><span style="color: #DD0000">"acidophilus"</span><span style="color: #007700">, </span><span style="color: #0000BB">$flavour</span><span style="color: #007700">)<br />{<br /> return </span><span style="color: #DD0000">"Making a bowl of </span><span style="color: #0000BB">$type</span><span style="color: #DD0000"> </span><span style="color: #0000BB">$flavour</span><span style="color: #DD0000">.\n"</span><span style="color: #007700">;<br />}<br /> <br />echo </span><span style="color: #0000BB">makeyogurt</span><span style="color: #007700">(</span><span style="color: #DD0000">"raspberry"</span><span style="color: #007700">); </span><span style="color: #FF8000">// won't work as expected<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<p class="para">
The output of the above example is:
</p>
<p class="para">
<div class="example-contents screen"><br />
Warning: Missing argument 2 in call to makeyogurt() in <br />
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41<br />
Making a bowl of raspberry .<br />
</div>
</p>
<p class="para">
Now, compare the above with this:
</p>
<p class="para">
</p><div class="example">
<p><b>Example #6 Correct usage of default function arguments</b></p>
<div class="example-contents programlisting">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">makeyogurt</span><span style="color: #007700">(</span><span style="color: #0000BB">$flavour</span><span style="color: #007700">, </span><span style="color: #0000BB">$type </span><span style="color: #007700">= </span><span style="color: #DD0000">"acidophilus"</span><span style="color: #007700">)<br />{<br /> return </span><span style="color: #DD0000">"Making a bowl of </span><span style="color: #0000BB">$type</span><span style="color: #DD0000"> </span><span style="color: #0000BB">$flavour</span><span style="color: #DD0000">.\n"</span><span style="color: #007700">;<br />}<br /> <br />echo </span><span style="color: #0000BB">makeyogurt</span><span style="color: #007700">(</span><span style="color: #DD0000">"raspberry"</span><span style="color: #007700">); </span><span style="color: #FF8000">// works as expected<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div><p>
</p>
<p class="para">
The output of this example is:
</p>
<p class="para">
<div class="example-contents screen"><br />
Making a bowl of acidophilus raspberry.<br />
</div>
</p>
<blockquote><p><b class="note">Note</b>:
<span class="simpara">
As of PHP 5, default values may be passed by reference.
</span>
</p></blockquote>
</div>
<div id="functions.variable-arg-list" class="sect2">
<h3 class="title">Variable-length argument lists</h3>
<p class="simpara">
PHP 4 and above has support for variable-length argument lists in
user-defined functions. This is really quite easy, using the
<a href="function.func-num-args.php" class="function">func_num_args()</a>,
<a href="function.func-get-arg.php" class="function">func_get_arg()</a>, and
<a href="function.func-get-args.php" class="function">func_get_args()</a> functions.
</p>
<p class="simpara">
No special syntax is required, and argument lists may still be
explicitly provided with function definitions and will behave as
normal.
</p>
</div>
</div><?php manual_footer(); ?>
