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

CKTIS / PHP

Parâmetro passado por referência (`&$list`)

O símbolo `&` antes de `$list` permite a uma função PHP alterar a variável usada na chamada. Escreve-se na declaração do parâmetro, não junto do argumento na chamada.

Versão: PHP 8.3

Sintaxe

<?php
function appendItem(array &$list, string $item): void
{
    $list[] = $item;
}

$items = ['apple'];
appendItem($items, 'pear');

Em PHP 8.3, &$list declara um parâmetro passado por referência. Na chamada appendItem($items, 'pear'), o nome local $list torna-se um alias para o mesmo conteúdo de $items. Uma referência em PHP não é um ponteiro para um endereço de memória. $list é um nome de parâmetro comum, sem relação com a construção list() usada para desestruturar arrays.

A sintaxe das referências, as operações sobre arrays e a função implode() usadas no exemplo não requerem extensões opcionais do PHP.

Escreve & antes do nome do parâmetro na declaração, não antes do argumento na chamada. Passa uma variável como $items; passar um literal como ['apple'] a esse parâmetro provoca um erro. Um resultado devolvido por referência também é válido. Receber um argumento por referência não implica devolver um resultado por referência.

$list[] = $item acrescenta um elemento ao array da variável usada na chamada, e $list = [] substituiria todo o array. As alterações continuam visíveis após a chamada. Já unset($list) no interior da função apenas remove a ligação local, não $items. Sem &, a passagem é por valor por omissão, pelo que o acrescento do exemplo não alteraria $items.

Em array &$list, o PHP verifica o tipo array à entrada na função, não à saída. Passar uma variável que contém um inteiro provoca um TypeError. void descreve o valor devolvido, não a alteração do argumento. Usa referências quando pretenderes alterar a variável usada na chamada e documenta esse efeito secundário, pois não é visível na chamada.

Exemplos

<?php
function appendItem(array &$list, string $item): void
{
    $list[] = $item;
}

$items = ['apple'];
appendItem($items, 'pear');
echo implode(', ', $items), "\n";

Resultado

apple, pear

Depois de chamar `appendItem()`, o programa mostra `$items`, não um valor devolvido pela função. A linha esperada é `apple, pear`. Para comparar, retira apenas `&` da declaração do parâmetro: a linha esperada passa a ser `apple`.

Lições relacionadas

  • PHP · Lição 20 · Intermédio · Versão: 3

Fontes