Returning values

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 return for more information.

Version Description
7.0.0 Added Return Type Declarations

Note:

If the return is omitted the value NULL will be returned.

Use of return

Example #1 Use of return

<?php
function square($num)
{
    return 
$num $num;
}
echo 
square(4);   // outputs '16'.
?>

A function can not return multiple values, but similar results can be obtained by returning an array.

Example #2 Returning an array to get multiple values

<?php
function small_numbers()
{
    return array (
012);
}
list (
$zero$one$two) = small_numbers();
?>

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:

Example #3 Returning a reference from a function

<?php
function &returns_reference()
{
    return 
$someref;
}

$newref =& returns_reference();
?>

For more information on references, please check out References Explained.

Return Type Declarations

PHP 7 Introduces Return type declaration where function can be forced to return type that is defined. This is done by setting declare(strict_types=1), if declare strict_type directive is set to 0 or not set functions are weakly type checked. The directive will have affect on all functions delcared in the file and not functions either included by this file or files that includes this file, are affected. The place where the function is called from is irrelavent. Declarable types are Classes, Interfaces, Array, Int, Float, String and Bool.

Example #4 Affect of strict_types directive

<?php
declare(strict_types=1); // file1.php

// file 1 - strictly type checked
// file 2 - weakly type checked

include "file2.php";

var_dump(a()); // works correctly
var_dump(b()); // fatal TypeError


function b() : int{
   return 
"1";  
}
?>


<?php
// file2.php
function a(): int{
   return 
"1";
}

?>

Example #5 More Return types

The function signature must match of the parent, if the parent has not been declared the return type the child can declare a type.

<?php
declare(strict_types=1);

interface 
Numbers{
  abstract public function 
one() : int ;
  abstract public function 
two();         // no return type defined
}

class 
NumClass implements Numbers
{
  public function 
one()  : int {  // return type same as abstract
    
return 0;
  }

  public function 
two()  {  // return type defined due lack of return type
    
return 2;               // in parent abstract function
  
}
}

class 
display extends NumClass
{
  public function 
one() : int // return type same as parent
  
{
    return 
1;
  }

  public function 
two() : int // return type same as parent
  
{
    return 
2;
  }
}

$dis = new display();
var_dump($dis->one());
var_dump($dis->two());

?>

Example #6 Return a class

<?php
declare(strict_types=1);

interface 
{
    static function 
make();
}
class 
implements {
    static function 
make(): //valid
        
return new B();
    }
}

Example #7 TypeError

Incorrect return type will result in a TypeError

<?php
declare(strict_types=1);

function 
show(): int{
    return 
"1";
}

try {
    
show();    
} catch (
TypeError $e) {
 
var_dump($e->getMessage()); // string(121) "Return value of show() must be of the type integer, 
                             // string returned in %s on line 5"
}
?>

add a note add a note

User Contributed Notes 6 notes

up
12
rstaveley at seseit dot com
4 years ago
Developers with a C background may expect pass by reference semantics for arrays. It may be surprising that  pass by value is used for arrays just like scalars. Objects are implicitly passed by reference.

<?php

# (1) Objects are always passed by reference and returned by reference

class Obj {
    public
$x;
}

function
obj_inc_x($obj) {
   
$obj->x++;
    return
$obj;
}

$obj = new Obj();
$obj->x = 1;

$obj2 = obj_inc_x($obj);
obj_inc_x($obj2);

print
$obj->x . ', ' . $obj2->x . "\n";

# (2) Scalars are not passed by reference or returned as such

function scalar_inc_x($x) {
   
$x++;
    return
$x;
}

$x = 1;

$x2 = scalar_inc_x($x);
scalar_inc_x($x2);

print
$x . ', ' . $x2 . "\n";

# (3) You have to force pass by reference and return by reference on scalars

function &scalar_ref_inc_x(&$x) {
   
$x++;
    return
$x;
}

$x = 1;

$x2 =& scalar_ref_inc_x($x);    # Need reference here as well as the function sig
scalar_ref_inc_x($x2);

print
$x . ', ' . $x2 . "\n";

# (4) Arrays use pass by value sematics just like scalars

function array_inc_x($array) {
   
$array{'x'}++;
    return
$array;
}

$array = array();
$array['x'] = 1;

$array2 = array_inc_x($array);
array_inc_x($array2);

print
$array['x'] . ', ' . $array2['x'] . "\n";

# (5) You have to force pass by reference and return by reference on arrays

function &array_ref_inc_x(&$array) {
   
$array{'x'}++;
    return
$array;
}

$array = array();
$array['x'] = 1;

$array2 =& array_ref_inc_x($array); # Need reference here as well as the function sig
array_ref_inc_x($array2);

print
$array['x'] . ', ' . $array2['x'] . "\n";
up
10
bgalloway at citycarshare dot org
7 years ago
Be careful about using "do this thing or die()" logic in your return lines.  It doesn't work as you'd expect:

<?php
function myfunc1() {
    return(
'thingy' or die('otherthingy'));
}
function
myfunc2() {
    return
'thingy' or die('otherthingy');
}
function
myfunc3() {
    return(
'thingy') or die('otherthingy');
}
function
myfunc4() {
    return
'thingy' or 'otherthingy';
}
function
myfunc5() {
   
$x = 'thingy' or 'otherthingy'; return $x;
}
echo
myfunc1(). "\n". myfunc2(). "\n". myfunc3(). "\n". myfunc4(). "\n". myfunc5(). "\n";
?>

Only myfunc5() returns 'thingy' - the rest return 1.
up
6
nick at itomic.com
11 years ago
Functions which return references, may return a NULL value. This is inconsistent with the fact that function parameters passed by reference can't be passed as NULL (or in fact anything which isnt a variable).

i.e.

<?php

function &testRet()
{
    return
NULL;
}

if (
testRet() === NULL)
{
    echo
"NULL";
}
?>

parses fine and echoes NULL
up
2
ian at NO_SPAM dot verteron dot net
12 years ago
In reference to the poster above, an additional (better?) way to return multiple values from a function is to use list(). For example:

function fn($a, $b)
{
   # complex stuff

   return array(
      $a * $b,
      $a + $b,
   );
}

list($product, $sum) = fn(3, 4);

echo $product; # prints 12
echo $sum; # prints 7
up
-2
Anonymous
5 years ago
As of at least PHP 5.3, a function or class method returning an object acts like an object.

<?php

class A {
    function
test() {
        echo
"Yay!";
        }
    }

function
get_obj() {
    return new
A();
    }

get_obj()->test();  // "Yay!"

?>

Sorry, still doesn't work with arrays.  Ie <?php echo get_array()[1]; ?> fails.
up
-19
ahmad at myandmyhost dot comze dot com
1 year ago
we can return array using foreach
<?php
function my_func2()
{
    return array(
"Name"=>"Ahmad Sayeed","Email"=>"ahmad@gmail.com");
   
}
$ar = my_func2();
foreach(
$ar as $key=>$value)
{echo
$key." , ".$value,"<br />";}

?>
To Top