Argumentos de funções

Informações podem ser passadas para funções através da lista de argumentos, que é uma lista de expressões delimitados por vírgulas. Os argumentos são avaliados da esquerda para a direita.

O PHP suporta a passagem de argumentos por valor (o padrão), passagem por referência, e valores padrões de argumentos. lista de argumentos de tamanho variável também são suportadas.

Exemplo #1 Passando arrays para funções

<?php
function takes_array($input)
{
    echo 
"$input[0] + $input[1] = "$input[0]+$input[1];
}
?>

Fazendo argumentos serem passados por referência

Por padrão, argumentos de função são passados por valor (de forma que se você mudar o valor do parâmetro dentro da função, ele não é alterado fora da função). Para permitir que uma função modifique os seus argumentos, eles devem ser passados por referência.

Para ter um argumento para uma função sempre passado por referência, adicione antes dele um "e comercial" (&) ao nome do argumento na definição da função:

Exemplo #2 Passando parâmetros de função por referência

<?php
function add_some_extra(&$string)
{
    
$string .= ' e alguma coisa mais.';
}
$str 'Isto é uma string,';
add_some_extra($str);
echo 
$str;    // imprime 'Isto é uma string, e alguma coisa mais.'
?>

Valores padrão de argumentos

Uma função pode definir valores padrão no estilo C++ para argumentos escalares, como a seguir:

Exemplo #3 Utilizando parâmetros padrão em funções

<?php
function makecoffee($type "cappuccino")
{
    return 
"Fazendo uma xícara de café $type.\n";
}
echo 
makecoffee();
echo 
makecoffee(null);
echo 
makecoffee("espresso");
?>

O exemplo acima irá imprimir:

Fazendo uma xícara de café cappuccino.
Fazendo uma xícara de café .
Fazendo uma xícara de café espresso.

O PHP também permite o uso def arrays e do tipo especial NULL como valores padrões, por exemplo:

Exemplo #4 Usando tipos não escalares como valores padrões

<?php
function makecoffee($types = array("cappuccino"), $coffeeMaker NULL)
{
    
$device is_null($coffeeMaker) ? "hands" $coffeeMaker;
    return 
"Making a cup of ".join(", "$types)." with $device.\n";
}
echo 
makecoffee();
echo 
makecoffee(array("cappuccino""lavazza"), "teapot");
?>

O valor padrão precisa ser uma expressão constante, não (por exemplo) uma variável, um membro de classe ou uma chamada de função.

Note que usando argumentos padrão, qualquer padrão deve vir após os argumentos sem padrão: caso contrário, as coisas não funcionarão como esperado. Considere o seguinte trecho de código:

Exemplo #5 Uso incorreto de parâmetros padrão de função

<?php
function iogurtera ($tipo "azeda"$sabor)
{
    return 
"Fazendo uma taça de $sabor $tipo.\n";
}

echo 
iogurtera ("framboesa");   // não funciona como esperado
?>

O exemplo acima irá imprimir:

Warning: Missing argument 2 in call to makeyogurt() in
/usr/local/etc/httpd/htdocs/phptest/functest.html on line 41
Fazendo uma taça de framboesa.

Agora, compare o que está acima com este:

Exemplo #6 Uso correto de parâmetros padrão de função

<?php
function iogurtera ($sabor$tipo "azeda")
{
    return 
"Fazendo uma taça de $sabor $tipo.\n";
}

echo 
iogurtera ("framboesa");   // funciona
?>

O exemplo acima irá imprimir:

Fazendo uma taça de framboesa azeda.

Nota: A partir do PHP 5, os valores padrões são passados por referência.

Declarações de tipo

Nota:

Declaração de tipos também era conhecida como type hints no PHP 5.

Declarações de tipo permitem que funções requiram que parâmetros sejam de certos tipos ao chamá-los. Se o valor informado no parâmetro tiver um tipo incorreto então um erro é gerado: no PHP 5 será um erro fatal recuperável, enquanto que no PHP 7 irá lançar uma exceção TypeError

Para declarar o tipo o seu nome deve ser adicionado antes no nome do parâmetro. A declaração pode ser feita para aceitar NULL se o valor default do parâmetro for configurado também para NULL.

Tipos válidos

Tipo Descrição Versão PHP Mínima
Classe/interface O parâmetro precisa ser um instanceof da classe ou interface informada. PHP 5.0.0
self O parâmetro precisa ser um instanceof da mesma classe do método onde a função está definida. Somente pode ser utilizado em métodos de classe e instância. PHP 5.0.0
array O parâmetro precisa ser um array. PHP 5.1.0
callable O parâmetro precisa ser um callable válido. PHP 5.4.0
bool O parâmetro precisa ser um valor boolean. PHP 7.0.0
float O parâmetro precisa ser um número float. PHP 7.0.0
int O parâmetro precisa ser um número integer. PHP 7.0.0
string O parâmetro precisa ser uma string. PHP 7.0.0
iterable O parâmetro precisa ser um array ou um instanceof Traversable. PHP 7.1.0
object O parâmetro precisa ser um object. PHP 7.2.0
Aviso

Apelidos para os tipos escalares acima não são suportados. Apelidos serão tradados como nomes de classe ou interface. Por exemplo, utilizar boolean como parâmetro ou tipo de retorno irá requerer um argumento ou retorno que seja um instanceof de uma classe ou interface boolean, em vez do tipo bool:

<?php
 
function test(boolean $param) {}
 
test(true);
 
?>

O exemplo acima irá imprimir:

 Fatal error: Uncaught TypeError: Argument 1 passed to test() must be an instance of boolean, boolean given, called in - on line 1 and defined in -:1
 

Exemplos

Exemplo #7 Declaração de tipos em classes

<?php
class {}
class 
extends {}

// This doesn't extend C.
class {}

function 
f(C $c) {
    echo 
get_class($c)."\n";
}

f(new C);
f(new D);
f(new E);
?>

O exemplo acima irá imprimir:

C
D

Fatal error: Uncaught TypeError: Argument 1 passed to f() must be an instance of C, instance of E given, called in - on line 14 and defined in -:8
Stack trace:
#0 -(14): f(Object(E))
#1 {main}
  thrown in - on line 8

Exemplo #8 Declaração de tipos em interfaces

<?php
interface { public function f(); }
class 
implements { public function f() {} }

// This doesn't implement I.
class {}

function 
f(I $i) {
    echo 
get_class($i)."\n";
}

f(new C);
f(new E);
?>

O exemplo acima irá imprimir:

C

Fatal error: Uncaught TypeError: Argument 1 passed to f() must implement interface I, instance of E given, called in - on line 13 and defined in -:8
Stack trace:
#0 -(13): f(Object(E))
#1 {main}
  thrown in - on line 8

Exemplo #9 Passando parâmetros tipados por referência

Os tipos declarados de parâmetros de referência são verificados na entrada da função, mas não no retorno função, assim, depois que a função tiver retornado, o tipo de argumento pode ter mudado.

<?php
function array_baz(array &$param)
{
    
$param 1;
}
$var = [];
array_baz($var);
var_dump($var);
array_baz($var);
?>

O exemplo acima irá imprimir algo similar à:

int(1)

Fatal error: Uncaught TypeError: Argument 1 passed to array_baz() must be of the type array, int given, called in %s on line %d

Exemplo #10 Declaração de tipos nulificáveis

<?php
class {}

function 
f(C $c null) {
    
var_dump($c);
}

f(new C);
f(null);
?>

O exemplo acima irá imprimir:

object(C)#1 (0) {
}
NULL

Tipagem estrita

Por padrão, se possível, o PHP irá converter o tipo incorreto no tipo escalar esperado. Por exemplo, uma função que passa um parâmetro integer onde se espera uma string receberá o valor com o tipo string.

É possível habilitar o modo estrito arquivo a arquivo. No modo estrito somente uma variável do exato tipo especificado na declaração será aceito, ou uma exceção TypeError será lançada. A única exceção é o tipo integer que poderá ser entregue a uma função esperando um float. Chamadas a funções de dentro de funções internas não serão afetadas pelas declarações strict_types

Para habilitar o modo estrito, utilize a instrução declare com a definição strict_types:

Cuidado

Habilitar o modo estrito também afetará as declarações de tipo de retorno.

Nota:

A tipagem estrita se aplica a chamadas feitas a partir do arquivo em que a tipagem estrita foi habilitada, não necessariamente às funções declaradas com tipos. Se um arquivo sem tipagem estrita tentar fazer uma chamada a uma função com tipagem estrita, a preferência do chamador (tipagem fraca) será respeitada, e o valor será possivelmente convertido.

Nota:

A tipagem estrita somente ocorre para declarações de tipo escalar, e portanto requer PHP 7.0.0 ou posterior, dado que declarações escalares foram acrescentadas nessa versão.

Exemplo #11 Tipagem estrita

<?php
declare(strict_types=1);

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

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

O exemplo acima irá imprimir:

int(3)

Fatal error: Uncaught TypeError: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 9 and defined in -:4
Stack trace:
#0 -(9): sum(1.5, 2.5)
#1 {main}
  thrown in - on line 4

Exemplo #12 Tipagem fraca

<?php
function sum(int $aint $b) {
    return 
$a $b;
}

var_dump(sum(12));

// These will be coerced to integers: note the output below!
var_dump(sum(1.52.5));
?>

O exemplo acima irá imprimir:

int(3)
int(3)

Exemplo #13 Catching TypeError

<?php
declare(strict_types=1);

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

try {
    
var_dump(sum(12));
    
var_dump(sum(1.52.5));
} catch (
TypeError $e) {
    echo 
'Error: '.$e->getMessage();
}
?>

O exemplo acima irá imprimir:

int(3)
Error: Argument 1 passed to sum() must be of the type integer, float given, called in - on line 10

Número variável de argumentos

O PHP tem suporte para um número variável de argumentos nas funções definidas pelo usuário. Isso é implementado usando o token ... a partir do PHP 5.6, e usando as funções func_num_args(), func_get_arg(), e func_get_args() a partir do PHP 5.5.

... no PHP 5.6+

A partir do PHP 5.6 é possível incluir o indicador de lista de argumentos ... para informar que a função aceita um número variável de argumentos. Os argumentos serão passados na forma de um array. Por exemplo.

Exemplo #14 Utilizando ... para acessar argumentos variáveis

<?php
function sum(...$numbers) {
    
$acc 0;
    foreach (
$numbers as $n) {
        
$acc += $n;
    }
    return 
$acc;
}

echo 
sum(1234);
?>

O exemplo acima irá imprimir:

10

Você também pode utilizar ... quando chamando funções para transformar uma variável array, Traversable ou literal em uma lista de argumentos.

Exemplo #15 Utilizando ... para fornecer argumentos

<?php
function add($a$b) {
    return 
$a $b;
}

echo 
add(...[12])."\n";

$a = [12];
echo 
add(...$a);
?>

O exemplo acima irá imprimir:

3
3

Você pode especificar argumentos posicionais antes do indicador. .... Nesse caso comente os argumentos finais, que não pareiem com um argumento posicional, serão adicionados ao array gerado por ....

É também possível adicionar um type hint antes do indicador .... Se presente então todos os argumentos capturados por ... deverão ser objetos da classe informada.

Exemplo #16 Argumentos variáveis com type hint

<?php
function total_intervals($unitDateInterval ...$intervals) {
    
$time 0;
    foreach (
$intervals as $interval) {
        
$time += $interval->$unit;
    }
    return 
$time;
}

$a = new DateInterval('P1D');
$b = new DateInterval('P2D');
echo 
total_intervals('d'$a$b).' days';

// This will fail, since null isn't a DateInterval object.
echo total_intervals('d'null);
?>

O exemplo acima irá imprimir:

3 days
Catchable fatal error: Argument 2 passed to total_intervals() must be an instance of DateInterval, null given, called in - on line 14 and defined in - on line 2

Finalmente, você também pode passar argumentos variáveis por referência ao prefixar ... com um &.

Versões anteriores do PHP

Funções com argumentos variáveis não precisam de sintaxe específica. No entanto o acesso aos argumentos da função precisam utilizar. func_num_args(), func_get_arg() e func_get_args().

O primeiro exemplo acima seria implementado no PHP 5.5 e anteriores assim:

Exemplo #17 Acessando argumentos variáveis no PHP 5.5 e anteriores

<?php
function sum() {
    
$acc 0;
    foreach (
func_get_args() as $n) {
        
$acc += $n;
    }
    return 
$acc;
}

echo 
sum(1234);
?>

O exemplo acima irá imprimir:

10

add a note add a note

User Contributed Notes

There are no user contributed notes for this page.
To Top