phpday 2025 - Call For Papers

Parâmetros e argumentos de funções

Os parâmetros de uma função são declarados em sua assinatura. Informações podem ser passadas para funções através da lista de argumentos, que é uma lista de expressões delimitadas por vírgulas. Os argumentos são avaliados da esquerda para a direita, e o resultado é atribuído aos parâmetros da função, antes que a função seja efetivamente chamada (avaliação ansiosa).

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 parâmetros de uma função pode incluir uma vírgula final, que será ignorada. Isto é particularmente útil nos casos em que a lista de parâmetros é longa ou contém nomes de variáveis longos, tornando conveniente listar os parâmetros verticalmente.

Exemplo #2 Parâmetros 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.
)
{
// ...
}
?>

Passando argumentos 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 parâmetro na definição da função:

Exemplo #3 Passando argumentos 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 uma expressão constante como argumento em um parâmetro que espera ser passado por referência.

Valores padrão de parâmetros

Uma função pode definir valores padrão para parâmetros usando sintaxe similar à atribuição de uma variável. O padrão é usado apenas quando o argumento do parâmetro não é passado. Observe que passar null não atribui o valor padrão.

Exemplo #4 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 produzirá:

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

Valores padrões de parâmetro podem ser valores escalares, arrays, o tipo especial null e, a partir do PHP 8.1.0, objetos usando a sintaxe new ClassName().

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

<?php
function fazercafe($tipos = array("cappuccino"), $cafeteira = NULL)
{
$dispositivo = is_null($cafeteira) ? "mãos" : $cafeteira;
return
"Fazendo uma xícara de ".join(", ", $tipos)." com $dispositivo.\n";
}
echo
fazercafe();
echo
fazercafe(array("cappuccino", "lavazza"), "chaleira");?>

O exemplo acima produzirá:

Fazendo uma xícara de cappuccino com mãos.
Fazendo uma xícara de cappuccino, lavazza com chaleira.

Exemplo #6 Usando objetos como valores padrão (a partir do PHP 8.1.0)

<?php
class CafeteiraPadrao {
public function
preparar() {
return
'Fazendo café.\n';
}
}
class
CafeteiraChique {
public function
preparar() {
return
'Preparando um belo café só para você.\n';
}
}
function
fazercafe($cafeteira = new CafeteiraPadrao)
{
return
$cafeteira->preparar();
}
echo
fazercafe();
echo
fazercafe(new CafeteiraChique);
?>

O exemplo acima produzirá:

Fazendo café.
Preparando um belo café só para você.

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.

Observe que quaisquer parâmetros opcionais devem ser especificados após os parâmetros obrigatórios, caso contrário, eles não podem ser omitidos das chamadas. Considere o seguinte exemplo:

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

<?php
function fazeriogurte($recipiente = "tigela", $sabor)
{
return
"Fazendo um(a) $recipiente de iogurte de $sabor.\n";
}

echo
fazeriogurte("framboesa"); // "framboesa" é $recipiente, não $sabor
?>

O exemplo acima produzirá:

Fatal error: Uncaught ArgumentCountError: Too few arguments
 to function fazeriogurte(), 1 passed in example.php on line 42

Agora, compare o que está acima com este:

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

<?php
function fazeriogurte($sabor, $recipiente = "tigela")
{
return
"Fazendo um(a) $recipiente de iogurte de $sabor.\n";
}

echo
fazeriogurte("framboesa"); // "framboesa" é $sabor
?>

O exemplo acima produzirá:

Fazendo um(a) tigela de iogurte de framboesa.

A partir do PHP 8.0.0, argumentos nomeados podem ser usados para pular vários parâmetros opcionais.

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

<?php
function fazeriogurte($recipiente = "tigela", $sabor = "framboesa", $estilo = "Grego")
{
return
"Fazendo um(a) $recipiente de iogurte $estilo de $sabor.\n";
}

echo
fazeriogurte(estilo: "natural");
?>

O exemplo acima produzirá:

Fazendo um(a) tigela de iogurte natural de framboesa.

A partir do PHP 8.0.0, declarar parâmetros obrigatórios após parâmetros opcionais está descontinuado. Isso geralmente pode ser resolvido descartando o valor padrão, pois nunca será usado. Uma exceção a essa regra são parâmetros no formato Type $param = null, onde o padrão null torna o tipo implicitamente anulável. Este uso foi descontinuado a partir do PHP 8.4.0, e um tipo anulável explícito deve ser usado.

Exemplo #10 Declarando parâmetros opcionais após parâmetros obrigatórios

<?php

function foo($a = [], $b) {} // Padrão não utilizado; descontinuado a partir do PHP 8.0.0
function foo($a, $b) {} // Funcionalmente equivalente, sem aviso de descontinuação

function bar(A $a = null, $b) {} // A partir do PHP 8.1.0, $a é implicitamente requerido
// (porque vem antes do parâmetro requerido),
// porém implicitamente anulável (descontinuado a partir do PHP 8.4.0),
// porque o valor padrão do parâmetro é null
function bar(?A $a, $b) {} // Recomendado

?>

Nota: A partir do PHP 7.1.0, omitir um parâmetro que não especifica um padrão lança um ArgumentCountError; em versões anteriores isso emitia um Aviso.

Nota: Parâmetros que esperam o argumento 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 ....

Listas de parâmetros podem conter o token ... para indicar que a função aceita um número variável de argumentos. Os argumentos serão passados na variável informada como um array:

Exemplo #11 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 produzirá:

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 #12 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 produzirá:

3
3

Podem ser especificados parâmetros 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 uma dica de tipo antes do indicador .... Se presente, todos os argumentos capturados por ... deverão conformar com o tipo do parâmetro.

Exemplo #13 Argumentos variáveis com dica de tipo

<?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';

// Isto falhará, já que null não é um objeto DateInterval.
echo total_intervals('d', null);
?>

O exemplo acima produzirá:

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, também podem ser passados argumentos variáveis por referência ao prefixar ... com um &.

Argumentos nomeados

O PHP 8.0.0 introduziu argumentos nomeados como uma extensão aos parâmetros posicionais. 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 com o nome do parâmetro e dois-pontos. Usar palavras reservadas como nomes de parâmetros é permitido. O nome de parâmetro precisa ser um identificador, e uma resolução dinâmica não é permitida.

Exemplo #14 Sintaxe dos argumentos nomeados

<?php
minhaFuncao
(nomeParametro: $valor);
array_foobar(array: $value);

// NÃO suportado
nome_funcao($variavelQueGuardaNomeDoParametro: $valor);
?>

Exemplo #15 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 #16 Mesmo exemplo com argumentos em ordem diferente

<?php
array_fill
(value: 50, count: 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 #17 Combinando argumentos posicionais e nomeados

<?php
htmlspecialchars
($string, double_encode: false);
// Mesmo que
htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);
?>

Passar o mesmo argumento mais de uma vez resulta em Uma exceção Error.

Exemplo #18 Erro lançado ao passar um argumento ao mesmo parâmetro nomeado múltiplas vezes

<?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

?>

A partir do PHP 8.1.0, é possível usar argumentos nomeados após desempacotar os argumentos. Um argumento nomeado não deve sobrepor argumentos já desempacotados.

Exemplo #19 Usando argumentos nomeados após desempacotar

<?php
function foo($a, $b, $c = 3, $d = 4) {
return
$a + $b + $c + $d;
}

var_dump(foo(...[1, 2], d: 40)); // 46
var_dump(foo(...['b' => 2, 'a' => 1], d: 40)); // 46

var_dump(foo(...[1, 2], b: 20)); // Fatal error. Named parameter $b overwrites previous argument
?>
adicione uma nota

Notas Enviadas por Usuários (em inglês) 8 notes

up
131
php at richardneill dot org
9 years ago
To experiment on performance of pass-by-reference and pass-by-value, I used this script. Conclusions are below.

#!/usr/bin/php
<?php
function sum($array,$max){ //For Reference, use: "&$array"
$sum=0;
for (
$i=0; $i<2; $i++){
#$array[$i]++; //Uncomment this line to modify the array within the function.
$sum += $array[$i];
}
return (
$sum);
}

$max = 1E7 //10 M data points.
$data = range(0,$max,1);

$start = microtime(true);
for (
$x = 0 ; $x < 100; $x++){
$sum = sum($data, $max);
}
$end = microtime(true);
echo
"Time: ".($end - $start)." s\n";

/* Run times:
# PASS BY MODIFIED? Time
- ------- --------- ----
1 value no 56 us
2 reference no 58 us

3 valuue yes 129 s
4 reference yes 66 us

Conclusions:

1. PHP is already smart about zero-copy / copy-on-write. A function call does NOT copy the data unless it needs to; the data is
only copied on write. That's why #1 and #2 take similar times, whereas #3 takes 2 million times longer than #4.
[You never need to use &$array to ask the compiler to do a zero-copy optimisation; it can work that out for itself.]

2. You do use &$array to tell the compiler "it is OK for the function to over-write my argument in place, I don't need the original
any more." This can make a huge difference to performance when we have large amounts of memory to copy.
(This is the only way it is done in C, arrays are always passed as pointers)

3. The other use of & is as a way to specify where data should be *returned*. (e.g. as used by exec() ).
(This is a C-like way of passing pointers for outputs, whereas PHP functions normally return complex types, or multiple answers
in an array)

4. It's unhelpful that only the function definition has &. The caller should have it, at least as syntactic sugar. Otherwise
it leads to unreadable code: because the person reading the function call doesn't expect it to pass by reference. At the moment,
it's necessary to write a by-reference function call with a comment, thus:
$sum = sum($data,$max); //warning, $data passed by reference, and may be modified.

5. Sometimes, pass by reference could be at the choice of the caller, NOT the function definitition. PHP doesn't allow it, but it
would be meaningful for the caller to decide to pass data in as a reference. i.e. "I'm done with the variable, it's OK to stomp
on it in memory".
*/
?>
up
13
Simmo at 9000 dot 000
2 years ago
For anyone just getting started with php or searching, for an understanding, on what this page describes as a "... token" in Variable-length arguments:
https://www.php.net/manual/en/functions.arguments.php#functions.variable-arg-list
<?php

func
($a, ...$b)

?>
The 3 dots, or elipsis, or "...", or dot dot dot is sometimes called the "spread operator" in other languages.

As this is only used in function arguments, it is probably not technically an true operator in PHP. (As of 8.1 at least?).

(With having an difficult to search for name like "... token", I hope this note helps someone).
up
18
LilyWhite
3 years ago
It is worth noting that you can use functions as function arguments

<?php
function run($op, $a, $b) {
return
$op($a, $b);
}

$add = function($a, $b) {
return
$a + $b;
};

$mul = function($a, $b) {
return
$a * $b;
};

echo
run($add, 1, 2), "\n";
echo
run($mul, 1, 2);
?>

Output:
3
2
up
16
Hayley Watson
7 years ago
There are fewer restrictions on using ... to supply multiple arguments to a function call than there are on using it to declare a variadic parameter in the function declaration. In particular, it can be used more than once to unpack arguments, provided that all such uses come after any positional arguments.

<?php

$array1
= [[1],[2],[3]];
$array2 = [4];
$array3 = [[5],[6],[7]];

$result = array_merge(...$array1); // Legal, of course: $result == [1,2,3];
$result = array_merge($array2, ...$array1); // $result == [4,1,2,3]
$result = array_merge(...$array1, $array2); // Fatal error: Cannot use positional argument after argument unpacking.
$result = array_merge(...$array1, ...$array3); // Legal! $result == [1,2,3,5,6,7]
?>

The Right Thing for the error case above would be for $result==[1,2,3,4], but this isn't yet (v7.1.8) supported.
up
28
gabriel at figdice dot org
8 years ago
A function's argument that is an object, will have its properties modified by the function although you don't need to pass it by reference.

<?php
$x
= new stdClass();
$x->prop = 1;

function
f ( $o ) // Notice the absence of &
{
$o->prop ++;
}

f($x);

echo
$x->prop; // shows: 2
?>

This is different for arrays:

<?php
$y
= [ 'prop' => 1 ];

function
g( $a )
{
$a['prop'] ++;
echo
$a['prop']; // shows: 2
}

g($y);

echo
$y['prop']; // shows: 1
?>
up
12
boan dot web at outlook dot com
6 years ago
Quote:

"The declaration can be made to accept NULL values if the default value of the parameter is set to NULL."

But you can do this (PHP 7.1+):

<?php
function foo(?string $bar) {
//...
}

foo(); // Fatal error
foo(null); // Okay
foo('Hello world'); // Okay
?>
up
4
Luna
1 year ago
When using named arguments and adding default values only to some of the arguments, the arguments with default values must be specified at the end or otherwise PHP throws an error:

<?php

function test1($a, $c, $b = 2)
{
return
$a + $b + $c;
}

function
test2($a, $b = 2, $c)
{
return
$a + $b + $c;
}

echo
test1(a: 1, c: 3)."\n"; // Works
echo test2(a: 1, c: 3)."\n"; // ArgumentCountError: Argument #2 ($b) not passed

?>

I assume that this happens because internally PHP rewrites the calls to something like test1(1, 3) and test2(1, , 3). The first call is valid, but the second obviously isn't.
up
5
Hayley Watson
7 years ago
If you use ... in a function's parameter list, you can use it only once for obvious reasons. Less obvious is that it has to be on the LAST parameter; as the manual puts it: "You may specify normal positional arguments BEFORE the ... token. (emphasis mine).

<?php
function variadic($first, ...$most, $last)
{
/*etc.*/}

variadic(1, 2, 3, 4, 5);
?>
results in a fatal error, even though it looks like the Thing To Do™ would be to set $first to 1, $most to [2, 3, 4], and $last to 5.
To Top