<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Function arguments</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="functions.user-defined.html">User-defined functions</a></div>
<div class="next" style="text-align: right; float: right;"><a href="functions.returning-values.html">Returning values</a></div>
<div class="up"><a href="language.functions.html">Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><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. The arguments are
evaluated from left to right.
</p>
<p class="para">
PHP supports passing arguments by value (the default), <a href="functions.arguments.html#functions.arguments.by-reference" class="link">passing by
reference</a>, and <a href="functions.arguments.html#functions.arguments.default" class="link">default argument
values</a>. <a href="functions.arguments.html#functions.variable-arg-list" class="link">Variable-length
argument lists</a> are also supported, see also the function references for
<span class="function"><a href="function.func-num-args.html" class="function">func_num_args()</a></span>,
<span class="function"><a href="function.func-get-arg.html" class="function">func_get_arg()</a></span>, and
<span class="function"><a href="function.func-get-args.html" class="function">func_get_args()</a></span> for more information.
</p>
<p class="para">
<div class="example" id="example-154">
<p><strong>Example #1 Passing arrays to functions</strong></p>
<div class="example-contents">
<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>
<div class="sect2" id="functions.arguments.by-reference">
<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">
<div class="example" id="example-155">
<p><strong>Example #2 Passing function parameters by reference</strong></p>
<div class="example-contents">
<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>
</div>
<div class="sect2" id="functions.arguments.default">
<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">
<div class="example" id="example-156">
<p><strong>Example #3 Use of default parameters in functions</strong></p>
<div class="example-contents">
<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 class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Making a cup of cappuccino.
Making a cup of .
Making a cup of espresso.
</pre></div>
</div>
</div>
</p>
<p class="para">
PHP also allows the use of <span class="type"><a href="language.types.array.html" class="type array">array</a></span>s and the special type <strong><code>NULL</code></strong>
as default values, for example:
</p>
<p class="para">
<div class="example" id="example-157">
<p><strong>Example #4 Using non-scalar types as default values</strong></p>
<div class="example-contents">
<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 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">
<div class="example" id="example-158">
<p><strong>Example #5 Incorrect usage of default function arguments</strong></p>
<div class="example-contents">
<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 class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Warning: Missing argument 2 in call to makeyogurt() in
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Making a bowl of raspberry .
</pre></div>
</div>
</div>
</p>
<p class="para">
Now, compare the above with this:
</p>
<p class="para">
<div class="example" id="example-159">
<p><strong>Example #6 Correct usage of default function arguments</strong></p>
<div class="example-contents">
<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 class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Making a bowl of acidophilus raspberry.
</pre></div>
</div>
</div>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
As of PHP 5, arguments that are passed by reference may have a default value.
</span>
</p></blockquote>
</div>
<div class="sect2" id="functions.variable-arg-list">
<h3 class="title">Variable-length argument lists</h3>
<p class="simpara">
PHP has support for variable-length argument lists in
user-defined functions. This is really quite easy, using the
<span class="function"><a href="function.func-num-args.html" class="function">func_num_args()</a></span>,
<span class="function"><a href="function.func-get-arg.html" class="function">func_get_arg()</a></span>, and
<span class="function"><a href="function.func-get-args.html" class="function">func_get_args()</a></span> 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><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="functions.user-defined.html">User-defined functions</a></div>
<div class="next" style="text-align: right; float: right;"><a href="functions.returning-values.html">Returning values</a></div>
<div class="up"><a href="language.functions.html">Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
