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

CKTIS / PHP

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

Com `&$projects`, uma função pode alterar a variável do código que a chama. O `&` escreve-se na declaração do parâmetro, não na chamada.

Versão: PHP 8.3; extension availability may vary

Sintaxe

function addProject(array &$projects, string $name): void { $projects[] = $name; }
addProject($activeProjects, 'Beacon');

Em PHP 8.3, array &$projects declara um parâmetro passado por referência. Durante a chamada, $projects na função e $activeProjects no código que a chama são dois nomes para o mesmo conteúdo. Tanto acrescentar um elemento com $projects[] = $name como atribuir um novo array a $projects altera a variável do código que faz a chamada. A alteração continua visível depois da chamada; void indica que a função não devolve um resultado.

Escreve & apenas na declaração do parâmetro. Chama addProject($activeProjects, 'Beacon') sem &. Passa uma variável inicializada em vez de um literal de array como [], que provoca um erro nesta posição. Também podes passar uma referência devolvida por uma função; um valor de retorno normal não substitui uma variável.

O PHP verifica o tipo array à entrada da função, não à saída. Se a variável inicializada não contiver um array, a chamada lança um TypeError. No entanto, a declaração do parâmetro não garante que a função deixe um array na variável.

Sem &, o argumento é passado por valor por omissão: neste exemplo, o novo elemento seria acrescentado apenas ao array local. Usa uma referência quando pretenderes alterar a variável do código que faz a chamada e documenta esse efeito. Se a variável tiver de ficar inalterada, passa o array por valor e devolve um array atualizado.

Exemplos

<?php
function addProject(array &$projects, string $name): void
{
    $projects[] = $name;
}

$activeProjects = ['Atlas'];
echo implode(', ', $activeProjects), "\n";
addProject($activeProjects, 'Beacon');
echo implode(', ', $activeProjects), "\n";

Resultado

Atlas
Atlas, Beacon

A primeira linha mostra o estado antes da chamada. A segunda mostra que `Beacon` foi acrescentado a `$activeProjects`, embora `addProject()` não devolva nenhum resultado.

Lições relacionadas

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

Fontes