<!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>Returning values</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="functions.arguments.html">Function arguments</a></div>
<div class="next" style="text-align: right; float: right;"><a href="functions.variable-functions.html">Variable functions</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.returning-values" class="sect1">
<h2 class="title">Returning values</h2>
<p class="para">
Values are returned by using the optional return statement. Any
type may be returned, including arrays and objects. This causes the
function to end its execution immediately and pass control back to
the line from which it was called. See <span class="function"><a href="function.return.html" class="function">return</a></span>
for more information.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If the <span class="function"><a href="function.return.html" class="function">return</a></span> is omitted the value <strong><code>NULL</code></strong> will be
returned.
</p>
</p></blockquote>
<div class="sect2">
<h3 class="title">Use of return</h3>
<p class="para">
<div class="example" id="example-153">
<p><strong>Example #1 Use of <span class="function"><a href="function.return.html" class="function">return</a></span></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">square</span><span style="color: #007700">(</span><span style="color: #0000BB">$num</span><span style="color: #007700">)<br />{<br /> return </span><span style="color: #0000BB">$num </span><span style="color: #007700">* </span><span style="color: #0000BB">$num</span><span style="color: #007700">;<br />}<br />echo </span><span style="color: #0000BB">square</span><span style="color: #007700">(</span><span style="color: #0000BB">4</span><span style="color: #007700">); </span><span style="color: #FF8000">// outputs '16'.<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
A function can not return multiple values, but similar results can be
obtained by returning an array.
</p>
<p class="para">
<div class="example" id="example-154">
<p><strong>Example #2 Returning an array to get multiple 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">small_numbers</span><span style="color: #007700">()<br />{<br /> return array (</span><span style="color: #0000BB">0</span><span style="color: #007700">, </span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">2</span><span style="color: #007700">);<br />}<br />list (</span><span style="color: #0000BB">$zero</span><span style="color: #007700">, </span><span style="color: #0000BB">$one</span><span style="color: #007700">, </span><span style="color: #0000BB">$two</span><span style="color: #007700">) = </span><span style="color: #0000BB">small_numbers</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
To return a reference from a function, use the reference operator & in
both the function declaration and when assigning the returned value to a
variable:
</p>
<p class="para">
<div class="example" id="example-155">
<p><strong>Example #3 Returning a reference from a function</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">returns_reference</span><span style="color: #007700">()<br />{<br /> return </span><span style="color: #0000BB">$someref</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">$newref </span><span style="color: #007700">=& </span><span style="color: #0000BB">returns_reference</span><span style="color: #007700">();<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="simpara">
For more information on references, please check out <a href="language.references.html" class="link">References Explained</a>.
</p>
</div>
<div class="sect2" id="functions.returning-values.type-declaration">
<h3 class="title">Return type declarations</h3>
<p class="para">
PHP 7 adds support for return type declarations. Similarly to
<a href="functions.arguments.html#functions.arguments.type-declaration" class="link">argument type declarations</a>,
return type declarations specify the type of the value that will be
returned from a function. The same
<a href="functions.arguments.html#functions.arguments.type-declaration.types" class="link">types</a>
are available for return type declarations as are available for argument
type declarations.
</p>
<p class="para">
<a href="functions.arguments.html#functions.arguments.type-declaration.strict" class="link">Strict typing</a>
also has an effect on return type declarations. In the default weak mode,
returned values will be coerced to the correct type if they are not
already of that type. In strong mode, the returned value must be of the
correct type, otherwise a <a href="class.typeerror.html" class="classname">TypeError</a> will be thrown.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
When overriding a parent method, the child's method must match any return
type declaration on the parent. If the parent doesn't define a return
type, then the child method may do so.
</p>
</p></blockquote>
<div class="sect3" id="functions.returning-values.type-declaration.examples">
<h4 class="title">Examples</h4>
<div class="example" id="example-156">
<p><strong>Example #4 Basic return type declaration</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">sum</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #0000BB">$b</span><span style="color: #007700">): </span><span style="color: #0000BB">float </span><span style="color: #007700">{<br /> return </span><span style="color: #0000BB">$a </span><span style="color: #007700">+ </span><span style="color: #0000BB">$b</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #FF8000">// Note that a float will be returned.<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">sum</span><span style="color: #007700">(</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">2</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>
float(3)
</pre></div>
</div>
</div>
<div class="example" id="example-157">
<p><strong>Example #5 Strict mode in action</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">declare(</span><span style="color: #0000BB">strict_types</span><span style="color: #007700">=</span><span style="color: #0000BB">1</span><span style="color: #007700">);<br /><br />function </span><span style="color: #0000BB">sum</span><span style="color: #007700">(</span><span style="color: #0000BB">$a</span><span style="color: #007700">, </span><span style="color: #0000BB">$b</span><span style="color: #007700">): </span><span style="color: #0000BB">int </span><span style="color: #007700">{<br /> return </span><span style="color: #0000BB">$a </span><span style="color: #007700">+ </span><span style="color: #0000BB">$b</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">sum</span><span style="color: #007700">(</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">2</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">sum</span><span style="color: #007700">(</span><span style="color: #0000BB">1</span><span style="color: #007700">, </span><span style="color: #0000BB">2.5</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>
int(3)
Fatal error: Uncaught TypeError: Return value of sum() must be of the type integer, float returned in - on line 5 in -:5
Stack trace:
#0 -(9): sum(1, 2.5)
#1 {main}
thrown in - on line 5
</pre></div>
</div>
</div>
<div class="example" id="example-158">
<p><strong>Example #6 Returning an object</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">class </span><span style="color: #0000BB">C </span><span style="color: #007700">{}<br /><br />function </span><span style="color: #0000BB">getC</span><span style="color: #007700">(): </span><span style="color: #0000BB">C </span><span style="color: #007700">{<br /> return new </span><span style="color: #0000BB">C</span><span style="color: #007700">;<br />}<br /><br /></span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">getC</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>
object(C)#1 (0) {
}
</pre></div>
</div>
</div>
</div>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="functions.arguments.html">Function arguments</a></div>
<div class="next" style="text-align: right; float: right;"><a href="functions.variable-functions.html">Variable functions</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>
