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];
}
?>
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.'
?>
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.
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.
| Tipo | Descrição | Versão PHP Mínima |
|---|---|---|
| Classe/interface | O parametro 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étrodo onde a função está definida. Somente pode ser utilizado em métodos de classe e instância. | PHP 5.0.0 |
| array | O parametro precisa ser um array. | PHP 5.1.0 |
| callable | O parâmetro precis 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 |
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
Exemplo #7 Declaração de tipos em classes
<?php
class C {}
class D extends C {}
// This doesn't extend C.
class E {}
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 I { public function f(); }
class C implements I { public function f() {} }
// This doesn't implement I.
class E {}
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 Declaração de tipos nulificáveis
<?php
class C {}
function f(C $c = null) {
var_dump($c);
}
f(new C);
f(null);
?>
O exemplo acima irá imprimir:
object(C)#1 (0) {
}
NULL
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:
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 acrescenadas nessa versão.
Exemplo #10 Tipagem estrita
<?php
declare(strict_types=1);
function sum(int $a, int $b) {
return $a + $b;
}
var_dump(sum(1, 2));
var_dump(sum(1.5, 2.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 #11 Tipagem fraca
<?php
function sum(int $a, int $b) {
return $a + $b;
}
var_dump(sum(1, 2));
// These will be coerced to integers: note the output below!
var_dump(sum(1.5, 2.5));
?>
O exemplo acima irá imprimir:
int(3) int(3)
Exemplo #12 Catching TypeError
<?php
declare(strict_types=1);
function sum(int $a, int $b) {
return $a + $b;
}
try {
var_dump(sum(1, 2));
var_dump(sum(1.5, 2.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
O PHP tem suporte para um número variável de argumentos nas funções definidas pelo usuário. Isso é implementado usando o token ... no PHP 5.6 e posterior, e usando as funções func_num_args(), func_get_arg(), e func_get_args() no PHP 5.5 e posteriores.
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 #13 Utilizando ... para acessar argumentos variáveis
<?php
function sum(...$numbers) {
$acc = 0;
foreach ($numbers as $n) {
$acc += $n;
}
return $acc;
}
echo sum(1, 2, 3, 4);
?>
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 #14 Utilizando ... para fornecer argumentos
<?php
function add($a, $b) {
return $a + $b;
}
echo add(...[1, 2])."\n";
$a = [1, 2];
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 #15 Argumentos variáveis com type hint
<?php
function total_intervals($unit, DateInterval ...$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 &.
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 #16 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(1, 2, 3, 4);
?>
O exemplo acima irá imprimir:
10