PHP 7.0.33 Released

Retornando valores

Valores podem ser retornados utilizando a instrução opcional return. Qualquer tipo pode ser retornado, incluindo arrays e objetos. Isto faz com que as função termine sua execução imediatamente e passa o controle de volta para a linha de onde ela foi chamada. Veja a documentação da função return para maiores informações.

Nota:

Se return for omitido então o valor NULL será retornado.

Use of return

Exemplo #1 O uso de return

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

Você não pode retornar múltiplos valores a partir de uma função, mas resultados similares podem ser obtidos retornando um array.

Exemplo #2 Retornando um array para devolver vários valores

<?php
function numeros_pequenos()
{
    return array (
012);
}
list (
$zero$um$dois) = numeros_pequenos();
?>

Para retornar uma referência de uma função, use o operador de referência & em ambas a declaração da função e quando definindo o valor para a variável.

Exemplo #3 Retornando uma referência de uma função

<?php
function &retorna_referencia()
{
    return 
$alguma_referencia;
}

$nova_referencia =& retorna_referencia();
?>

Para mais detalhes sobre referências, leia a seção Referências.

Declaração de tipo de retorno

O PHP 7 acrescenta suporte a declaração de tipo de retorno. Similar à declaração de tipagem de argumentos, declaração de tipo de retorno especifica o tipo do valor que será retornado de uma função. Os mesmos tipos que estão disponíveis para declaração de argumentos estão disponíveis para tipagem de retornos.

A tipagem estrita também afeta a tipagem de retorno. No modo padrão (tripagem fraca) o valores retornados serão convertidos para o tipo correto caso não enquadrem no tipo informado. No modo de tipagem forte os valores retornados precisam ser o tipo correto ou uma exceção TypeError será lançada.

Nota:

Quando sobrescrevendo um método, o novo método precisa concidir com a tipagem de retorno do método anterior. Se o método sobrescrito não define uma tipagem de tipo, então o novo método precisa espelhar isso.

Exemplos

Exemplo #4 Declaração de tipo de retorno

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

// Note que um float será retornado.
var_dump(sum(12));
?>

O exemplo acima irá imprimir:

float(3)

Exemplo #5 Modo estrito em ação

<?php
declare(strict_types=1);

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

var_dump(sum(12));
var_dump(sum(12.5));
?>

O exemplo acima irá imprimir:

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

Exemplo #6 Returning an object

<?php
class {}

function 
getC(): {
    return new 
C;
}

var_dump(getC());
?>

O exemplo acima irá imprimir:

object(C)#1 (0) {
}
add a note add a note

User Contributed Notes 13 notes

up
32
ryan dot jentzsch at gmail dot com
1 year 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.
up
28
rstaveley at seseit dot com
8 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
20
bgalloway at citycarshare dot org
10 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
1
Berniev
7 months 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.
up
5
k-gun !! mail
1 year 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!
   
}
}
?>
up
8
ryan dot jentzsch at gmail dot com
3 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
up
7
nick at itomic.com
15 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
0
zored dot box at gmail dot com
9 months 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;
    }
}
?>
up
-6
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
up
-6
Vidmantas Maskoliunas
2 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.
up
-11
ian at NO_SPAM dot verteron dot net
15 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
-5
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;
up
-15
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;
    }

}
?>
To Top