Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / PHP

Parâmetro por referência `&$value` e passagem por valor

Em PHP 8.3, o parâmetro `&$value` permite que a função altere a variável de quem faz a chamada. Na passagem por valor, que é o modo predefinido, atribuir um valor ao parâmetro não altera essa variável.

Versão: PHP 8.3; extension availability may vary

Sintaxe

function addOneByReference(int &$value): void { $value += 1; }
$number = 5;
addOneByReference($number);

Na declaração int &$value, & indica a passagem por referência. O parâmetro local $value e a variável de quem chama a função são dois nomes para o mesmo valor; uma referência em PHP não é um ponteiro como em C. Uma atribuição a $value altera o valor visto por quem fez a chamada, e o fim da função não desfaz essa alteração.

Escreve & na declaração, não na chamada: addOneByReference($number). Passa uma variável ou o resultado de uma função que devolva explicitamente por referência. Um literal como 5 causa um erro; expressões comuns, como $number + 1, não são argumentos válidos neste caso. Um & antes do nome da função indica que o resultado é devolvido por referência, não que um parâmetro é passado por referência.

Sem &, a passagem é por valor: uma atribuição a $value só tem efeito local. Se o argumento for um objeto, ambas as variáveis podem ainda identificar o mesmo objeto. Alterar as suas propriedades pode, por isso, ter um efeito visível para quem fez a chamada, mas atribuir outro objeto ao parâmetro não altera a variável original.

Com int &$value, o tipo do parâmetro é verificado à entrada da função, não à saída. A declaração, por si só, não garante que uma variável comum de quem fez a chamada continue a ser do tipo int. Usa & quando a alteração dessa variável fizer parte do contrato da função e documenta esse efeito secundário. Caso contrário, considera devolver o novo valor.

Exemplos

<?php
declare(strict_types=1);

function addOneByValue(int $value): void
{
    $value += 1;
}

function addOneByReference(int &$value): void
{
    $value += 1;
}

$number = 5;
addOneByValue($number);
echo "by value: $number\n";

addOneByReference($number);
echo "by reference: $number\n";

Resultado

by value: 5
by reference: 6

As duas funções executam `$value += 1`. Após a chamada por valor, `$number` continua a valer `5`; após a chamada por referência, passa a valer `6`.

Lições relacionadas

  • PHP · Lição 77 · Avançado · Versão: 2

Fontes