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 e argumentos nomeados
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];
}
?>
A partir do PHP 8.0.0, a lista de argumentos de uma função pode incluir uma vírgula final,
que será ignorada. Isto é particularmente útil nos casos que a quantidade de argumentos é
longa ou contém nomes longos, sendo conveniente listar os argumentos verticalmente.
Exemplo #2 Argumentos de função com uma vírgula final
<?php
function takes_many_args(
$primeiro,
$segundo,
$uma_variavel_com_nome_longo,
$parametro_com_default = 5,
$de_novo = 'argumento padrão', // Essa vírgula final não era permitida antes do PHP 8.0.0.
)
{
// ...
}
?>
A partir do PHP 8.0.0, passar argumentos mandatórios após argumentos opcionais
é obsoleto. Isso geralmente pode ser resolvido através da eliminação dos argumentos opcionais.
Uma exceção são os argumentos na forma
Tipo $param = null
, onde o null
padrão torna o tipo implicitamente
nullable. Esta forma permanece permitida, entretanto é recomendável um tipo
explicitamente nullable nesses casos.
Exemplo #3 Passando argumentos opcionais depois de argumentos obrigatórios
<?php
function foo($a = [], $b) {} // Antes
function foo($a, $b) {} // Depois
function bar(A $a = null, $b) {} // Ainda permitido
function bar(?A $a, $b) {} // Recomendado
?>
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 #4 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.'
?>
É um erro passar um argumento por valor onde é esperado a passagem por referência.
Valores padrão de argumentos
Uma função pode definir valores padrão no estilo C++ para argumentos escalares, como
a seguir:
Exemplo #5 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 #6 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 #7 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 #8 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:
Argumentos passados por referência podem ter um valor padrão.
Número variável de argumentos
O PHP suporta argumentos em quantidade variável em
funções definidas pelo usuário, utilizando o token
...
.
Nota:
Também é possível emular argumentos variáveis utilizando as funções
func_num_args(),
func_get_arg(), e
func_get_args().
Esta técnica não é recomendada dado que ela era necessária apenas antes da introdução
do token ...
.
Lista de argumentos que contém o token
...
token para indicam que a função aceita uma
quantidade variável de argumentos. Os argumentos serão passados
na variável como um array. Por exemplo:
Exemplo #9 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:
Você também pode utilizar ...
quando chamando funções para
transformar uma variável array, Traversable ou
literal em uma lista de argumentos.
Exemplo #10 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:
Você pode especificar argumentos posicionais antes do indicador.
...
. Nesse caso comente os argumentos finais,
que não pareiam 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 #11 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
&
.
Versões anteriores do PHP
Funções com argumentos variáveis não precisam de sintaxe específica.
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 em versões anteriores do PHP:
Exemplo #12 Acessando argumentos variáveis em versões anteriores do PHP
<?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:
Named Arguments
O PHP 8.0.0 introduziu argumentos nomeados como uma extensão aos
parâmetros posionais. Argumentos nomeados permitem a passagem de argumentos para uma
função utilizando-se os nomes de parâmetros, ao invés da posição do parâmetro.
Isto torna o significado do argumento auto documentável, e tornam os argumentos
independente de ordem, além de permitir pular argumentos com defaults.
Argumentos nomeados são passados ao prefixar o valor um o nome do parâmetro
e um dois pontos. Usar palavras reservadas como nomes de parâmetro é permitido.
O nome de parâmetro precisa ser um identificados, e uma resolução dinâmica
não é permitida.
Exemplo #13 Sintaxe dos argumentos nomeados
<?php
minhaFuncao(nomeParametro: $valor);
array_foobar(array: $value);
// NÃO suportado
nome_funcao($variaveoQueGuardaNomeDoParametro: $valor);
?>
Exemplo #14 Comparando argumentos posicionais e nomeados
<?php
// Utilizando argumentos posicionais:
array_fill(0, 100, 50);
// Utilizando argumetos nomeados:
array_fill(start_index: 0, count: 100, value: 50);
?>
A ordem em que argumentos nomeados são passados não importa.
Exemplo #15 Mesmo exemplo com argumentos em ordem diferente
<?php
array_fill(value: 50, num: 100, start_index: 0);
?>
Argumentos nomeados podem ser combinados com argumentos posicionais. Nesse caso,
os argumentos nomeados precisam estar depois dos argumentos posicionais.
Também é possível especificar somente alguns dos argumentos opcionais de
uma função, independente da ordem.
Exemplo #16 Combinando argumentos posicionais e nomeados
<?php
htmlspecialchars($string, double_encode: false);
// Mesmo que
htmlspecialchars($string, ENT_COMPAT | ENT_HTML401, 'UTF-8', false);
?>
Passar o mesmo argumento mais de uma vez resulta em um Error.
Exemplo #17 Exceção ao passar o mesmo argumento nomeado mais de uma vez
<?php
function foo($param) { ... }
foo(param: 1, param: 2);
// Error: Named parameter $param overwrites previous argument
foo(1, param: 2);
// Error: Named parameter $param overwrites previous argument
?>