PHP: Returning values

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.

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 (0, 1, 2);
}
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 adds support for return type declarations. Similarly to argument type declarations, return type declarations specify the type of the value that will be returned from a function. The same types are available for return type declarations as are available for argument type declarations.

Strict typing 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 TypeError will be thrown.

As of PHP 7.1.0, return values can be marked as nullable by prefixing the type name with a question mark (?). This signifies that the function returns either the specified type or NULL.

Note:
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.

Examples

Example #4 Basic return type declaration


<?php
function sum($a, $b): float {
    return $a + $b;
}

// Note that a float will be returned.
var_dump(sum(1, 2));
?>

The above example will output:

float(3)

Example #5 Strict mode in action


<?php
declare(strict_types=1);

function sum($a, $b): int {
    return $a + $b;
}

var_dump(sum(1, 2));
var_dump(sum(1, 2.5));
?>

The above example will output:

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

Example #6 Returning an object


<?php
class C {}

function getC(): C {
    return new C;
}

var_dump(getC());
?>

The above example will output:

object(C)#1 (0) {
}

Example #7 Nullable return type declaration (as of PHP 7.1.0)


<?php
function get_item(): ?string {
    if (isset($_GET['item'])) {
        return $_GET['item'];
    } else {
        return null;
    }
}
?>

add a note

User Contributed Notes 13 notes

down

ryan dot jentzsch at gmail dot com ¶

2 years ago


PHP 7.1 allows for void and null return types by preceding the type declaration with a ? -- (e.g. function canReturnNullorString(): ?string) 

However resource is not allowed as a return type:

<?php
function fileOpen(string $fileName, string $mode): resource
{
    $handle = fopen($fileName, $mode);
    if ($handle !== false)
    {
        return $handle;
    }
}

$resourceHandle = fileOpen("myfile.txt", "r");
?>

Errors with:
Fatal error: Uncaught TypeError: Return value of fileOpen() must be an instance of resource, resource returned.

down

rstaveley at seseit dot com ¶

9 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";

down

bgalloway at citycarshare dot org ¶

11 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.

down

k-gun !! mail ¶

2 years ago


With 7.1, these are possible yet;

<?php
function ret_void(): void {
    // do something but no return any value
    // if needs to break fn exec for any reason simply write return;
    if (...) {
        return; // break
        // return null; // even this NO!
    }

    $db->doSomething();
    // no need return call anymore 
}

function ret_nullable() ?int {
    if (...) {
        return 123;
    } else {
        return null; // MUST!
    }
}
?>

down

zored dot box at gmail dot com ¶

1 year ago


You may specify child return type if there is no parent:

<?php

class A {
    public function f ($a)
    {
        return 1;
    }
}

class B extends A {
    public function f ($a): int // + return type, OK
    {
        return 1;
    }
}

class C extends A {
    public function f (int $a) // + argument type, WARNING
    {
        return 1;
    }
}
?>

down

ryan dot jentzsch at gmail dot com ¶

4 years ago


PHP 7 return types if specified can not return a null.
For example:
<?php
declare(strict_types=1);

function add2ints(int $x, int $y):int
{
    $z = $x + $y;
    if ($z===0)
    {
        return null;
    }
    return $z;
}
$a = add2ints(3, 4);
echo is_null($a) ? 'Null' : $a;
$b = add2ints(-2, 2);
echo is_null($b) ? 'Null' : $b;
exit();

Output:
7
Process finished with exit code 139

down

Berniev ¶

1 year ago


Be careful when introducing return types to your code.

Only one return type can be specified (but prefacing with ? allows null).

Return values of a type different to that specified are silently converted with sometimes perplexing results. These can be tedious to find and will need rewriting, along with calling code.

Declare strict types using "declare(strict_types=1);" and an error will be generated, saving much head-scratching.

down

nick at itomic.com ¶

16 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

down

-5

Vidmantas Maskoliunas ¶

3 years ago


Note: the function does not have "alternative syntax" as if/endif, while/endwhile, and colon (:) here is used to define returning type and not to mark where the block statement begins.

down

-7

Nathan Salter ¶

3 years ago


Just a quick clarification on whether variables are passed by reference or not. Variables are always passed using a pointer, and if the variable is modified, it is copied and re-assigned. For example:

<?php

function byPointer($x) {
    return $x / 3; // Does not modify or create a copy of $x
}

function copied($x) {
    $x++; // At this point, creates a copy of $x to be used in local scope
    return $x;
}

class Obj {
    public function performAction() {}
    public $y;
}

function objPointer(Obj $x) {
    $x->performAction(); //works on $x
    $x->y = '150'; //works on $x
    $x = new Obj(); // Does not modify $x outside of function
    $x->y = '250';
}

function objReference(Obj &$x) {
    $x->performAction(); //works on $x
    $x->y = '150'; //works on $x
    $x = new Obj(); // Modifies original $x outside of function
    $x->y = '250';
}

$x = new Obj();
$x->y = '10';

objPointer($x);

echo "Post Pointer: {$x->y}\n";

$x->y = '10';
objReference($x);

echo "Post Reference: {$x->y}\n";

?>

This will output:
Post Pointer: 150
Post Reference: 250

So make sure when writing functions that if you want to pass by reference you actually mean by reference, and not using standard PHP pointers

down

-10

ian at NO_SPAM dot verteron dot net ¶

16 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

down

-7

Ahmed KOOLI ¶

1 year ago


If a function/method parameter has a type declaration , then php compiler will check it the moment of invocation regardless if strict_types is set to 1 or 0 or not set at all.

However, php will check parameters types on build in php functions when  strict_types is set to 1;

down

-17

ortreum ¶

2 years ago


I like this method of concatinating methods by returning $this. It makes my code more readable. If the returned value is not an object it will fail and you find mistakes easier.

<?php
class Dummy {

    private $result;

    function __construct()
    {
        $this->result =
            $this
                ->setStuff('abc')
                ->generateResult()
            ;
    }
    
    function setStuff($value)
    {
        // do something
        return $this;
    }

    function generateResult()
    {
        return ['the result'];
    }

    function getResult()
    {
        return $this->result;
    }

}
?>

add a note