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

CKTIS / PHP

Parâmetro do tipo array passado por referência: `array &$items`

`array &$items` exige um array no início da chamada e permite que a função altere a variável de quem a chama, sem devolver um resultado.

Versão: PHP 8.3; extension availability may vary

Sintaxe

function markReady(array &$items): void { $items[0] = 'ready'; }
$cart = ['draft'];
markReady($cart);

Em function markReady(array &$items): void, array declara o tipo de entrada, $items é o nome local do parâmetro e & indica a passagem por referência. O parâmetro é um alias da variável de quem chama a função: tanto escrever em $items[0] como atribuir um novo valor a $items tem um efeito visível fora da função, mesmo com : void.

Inicializa uma variável com um array e chama markReady($cart). O & escreve-se na declaração, não na chamada. Não passes diretamente um literal de array como ['draft'] nem um resultado normal devolvido por valor; podes passar um resultado devolvido por referência. Se a variável fornecida não contiver um array, o PHP lança TypeError à entrada. O tipo não é verificado novamente à saída, pelo que uma atribuição através de $items pode até mudar o tipo de uma variável comum de quem fez a chamada.

Sem &, array $items é passado por valor: substituir um elemento que contém uma cadeia de caracteres simples, como no exemplo, não altera o array de quem fez a chamada. Não se trata de uma cópia profunda: referências já existentes no array podem continuar a partilhar valores. Se a alteração não fizer parte do contrato da função, recebe o array por valor e devolve explicitamente o resultado.

unset($items) remove a ligação local, não a variável de quem fez a chamada. Por sua vez, foreach ($items as &$item) cria uma referência distinta para um elemento. Usa unset($item) depois desse ciclo para que uma escrita posterior em $item não substitua o último elemento percorrido.

Exemplos

<?php
function markReadyCopy(array $items): void
{
    $items[0] = 'ready';
}

function markReady(array &$items): void
{
    $items[0] = 'ready';
}

$cart = ['draft'];
markReadyCopy($cart);
echo $cart[0], "\n";

markReady($cart);
echo $cart[0], "\n";

Resultado

draft
ready

Ambas as funções escrevem `ready` no índice `0`. Após a passagem por valor, `$cart[0]` continua a conter `draft`; após a passagem por referência, contém `ready`.

Lições relacionadas

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

Fontes