unset()

Introdução

A função unset() é uma função embutida do PHP que destrói uma variável ou um elemento de um array. Após uma variável ser removida com unset, ela deixa de existir — referenciá-la novamente se comporta exatamente como se ela nunca tivesse sido declarada.

Esta página abrange a sintaxe de unset(), como ela se comporta com arrays, referências, propriedades de objetos e variáveis dentro de funções, e como ela difere de simplesmente atribuir null. Conhecer essas diferenças ajuda você a escrever código previsível e evitar as armadilhas mais comuns de unset().

Um ponto fundamental a entender desde o início: unset() remove o nome (a ligação da variável), não necessariamente o valor subjacente. O PHP libera a memória do valor automaticamente por meio de contagem de referências e seu coletor de lixo quando nada mais aponta para ele — não no momento exato em que você chama unset().

Sintaxe

unset(mixed $var, mixed ...$vars): void

A função aceita uma ou mais variáveis (separadas por vírgulas) e não retorna nada (void). Cada argumento é a variável ou elemento de array que você deseja destruir.

<?php
$a = 1;
$b = 2;
$c = 3;
unset($a, $b, $c); // destroy several variables in one call
?>

Removendo um elemento de array

O uso mais comum de unset() é excluir um elemento de um array pela sua chave:

Exemplo de unset() no PHP

Aqui removemos o elemento no índice 1 ("banana"). A saída é:

Array
(
    [0] => apple
    [2] => cherry
)

Observe que unset() não reindexa o array — as chaves restantes permanecem 0 e 2, deixando uma "lacuna". Esta é a surpresa mais frequente com unset(). Se você precisar de uma lista limpa e sequencialmente reindexada (0, 1, 2, …), passe o resultado pela função array_values():

<?php
$array = ["apple", "banana", "cherry"];
unset($array[1]);
$array = array_values($array);
print_r($array);
?>

Array
(
    [0] => apple
    [1] => cherry
)

Destruindo uma variável independente

Quando chamada em uma variável simples, unset() a remove completamente. Depois disso, a variável é tratada como indefinida:

<?php
$name = "John";
unset($name);
echo $name ?? "Variable is unset"; // Outputs: Variable is unset
?>

O operador de coalescência nula ?? é a forma segura de ler uma variável possivelmente removida, pois ele não emite um aviso de "Variável indefinida". Usar isset() é outra forma comum de verificar se uma variável ainda existe.

unset() vs. atribuir null

Esses dois parecem similares, mas não são iguais:

<?php
$x = 5;
$y = 5;

unset($x);   // $x no longer exists
$y = null;   // $y still exists, its value is null

var_dump(isset($x)); // bool(false) — the variable is gone
var_dump(isset($y)); // bool(false) — isset() returns false for null too
var_dump(array_key_exists('y', get_defined_vars())); // bool(true) — $y is still defined
?>

Use unset() quando você quiser que a variável (ou chave de array) não exista. Atribua null quando quiser manter a variável, mas limpar seu valor. Note que isset() retorna false em ambos os casos, portanto, para distingui-los, você deve verificar a existência da chave diretamente. Consulte is_null() e empty() para verificações relacionadas.

unset() dentro de uma função

O comportamento de unset() depende do escopo da variável, e isso surpreende muitos desenvolvedores:

<?php
function destroy_local() {
    $value = 10;
    unset($value); // only the local copy is destroyed
    echo $value ?? "local is unset"; // Outputs: local is unset
}
destroy_local();
?>

Quando você aplica unset() em uma variável passada por referência, apenas a referência local é quebrada — a variável do chamador não é alterada:

<?php
function destroy_ref(&$ref) {
    unset($ref); // breaks the local binding, not the original
}

$data = "keep me";
destroy_ref($data);
echo $data; // Outputs: keep me
?>

Se você realmente precisar que uma função remova uma variável do escopo chamador, passe-a como um elemento de array referenciado ou use uma global — mas na maioria dos casos, redesenhar para retornar um valor é mais limpo. Para mais informações sobre regras de escopo, consulte Variables Scope.

Removendo propriedades de objetos

unset() também remove uma propriedade de uma instância de objeto:

<?php
$user = new stdClass();
$user->name = "Ann";
$user->role = "admin";

unset($user->role);
var_dump(isset($user->role)); // bool(false)
print_r($user);
?>

bool(false)
stdClass Object
(
    [name] => Ann
)

A armadilha da referência no foreach

Um bug clássico: após iterar um array com uma referência (&$value), a variável de referência ainda aponta para o último elemento. Reutilizá-la posteriormente corrompe silenciosamente o array. A solução é aplicar unset() na referência logo após o loop:

<?php
$items = [1, 2, 3];
foreach ($items as &$value) {
    $value *= 2;
}
unset($value); // break the dangling reference — do this every time

print_r($items);
?>

Array
(
    [0] => 2
    [1] => 4
    [2] => 6
)

Conclusão

unset() destrói variáveis, elementos de array e propriedades de objetos, removendo a ligação para que o nome deixe de existir. Tenha estes pontos em mente:

• Ela remove o nome, não necessariamente o valor — a memória é liberada pela contagem de referências e pelo coletor de lixo do PHP.
• Remover um elemento de array deixa uma lacuna; use array_values() para reindexar.
• Não é o mesmo que atribuir null; unset() faz a variável deixar de existir.
• Dentro de funções, respeita o escopo, e remover um parâmetro passado por referência quebra apenas a ligação local.
• Sempre aplique unset() na variável do loop após um laço foreach ... as &$value.

Para aprender mais sobre como trabalhar com os dados em que unset() opera, explore PHP Variables e PHP Arrays.

Prática