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 argumento na definição da função:

<?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 para argumentos usando sintaxe similar a atribuição de uma variável. O padrão é usado apenas quando o parâmetro não é especificado. Em particular, note que passar null não atribui o valor padrão.

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

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().

<?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");?>

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

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

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.

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

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

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

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:

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

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

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.

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

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

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

A partir do PHP 8.0.0, declarar argumentos obrigatórios após argumentos 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 argumentos no formato Type $param = null, onde o padrão null torna o tipo implicitamente anulável. Este uso continua permitido, embora seja recomendado usar um tipo anulável explícito.

<?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) {} // Ainda permitido; $a é obrigatório porém anulável
 function bar(?A $a, $b) {}       // Recomendado
 ?>

Note: 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.

Note: 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 ....

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:

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

echo sum(1, 2, 3, 4);
?>

10

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

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

echo add(...[1, 2])."\n";

$a = [1, 2];
echo add(...$a);
?>

3
3

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 conformar com o tipo do parâmetro.

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

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 &.

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

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

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

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

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

<?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 um Error.

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

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