Array associativo em PHP: pares de chave e valor

Um array associativo guarda cada valor sob uma chave que você escolhe, escrita como key => value: $user = ['name' => 'Ada', 'age' => 36];. Leia um valor com $user['name'], e adicione ou altere um atribuindo à chave: $user['email'] = 'ada@example.com';.

<?php
$user = [
    'name' => 'Ada',
    'age'  => 36,
    'city' => 'London',
];

echo $user['name'], "\n";
echo $user['age'], "\n";

$user['email'] = 'ada@example.com';   // add a pair
$user['city']  = 'Paris';             // change a value

print_r($user);

Em outras linguagens, a mesma estrutura se chama dicionário, map ou hash. No PHP, é um array comum cujas chaves são strings em vez de 0, 1, 2.

Adicionar, alterar e remover pares

Atribuir a uma chave que não existe a adiciona no fim. Atribuir a uma chave que existe substitui o valor e mantém a posição. unset() remove um par.

<?php
$stock = ['apples' => 10, 'pears' => 4];

$stock['plums'] = 7;      // new key: added at the end
$stock['apples'] = 12;    // existing key: value replaced
$stock['pears']--;        // change in place
unset($stock['plums']);   // remove a pair

print_r($stock);

array_push() não ajuda aqui: ele só acrescenta valores com chaves numéricas. Para adicionar vários pares de uma vez, use array_merge($stock, $more), em que os novos valores vencem, ou $stock + $more, em que as chaves existentes mantêm os valores; a página sobre array_merge compara os dois.

Percorrer chaves e valores

foreach ($array as $key => $value) percorre os pares na ordem em que foram adicionados. Tire o $key => quando você só precisa dos valores.

<?php
$capitals = [
    'France'  => 'Paris',
    'Japan'   => 'Tokyo',
    'Brazil'  => 'Brasília',
];

foreach ($capitals as $country => $capital) {
    echo "The capital of $country is $capital.\n";
}

foreach ($capitals as $capital) {
    echo mb_strtoupper($capital), "\n";
}

Pegar todas as chaves ou todos os valores

array_keys() retorna as chaves como uma lista simples e array_values() retorna os valores, os dois reindexados a partir de 0. Passe um segundo argumento ao array_keys() e ele retorna só as chaves que guardam aquele valor, que é como você encontra todas as chaves de um valor.

<?php
$grades = ['Ada' => 'A', 'Linus' => 'B', 'Grace' => 'A'];

print_r(array_keys($grades));
print_r(array_values($grades));
print_r(array_keys($grades, 'A'));    // keys whose value is 'A'

echo array_search('B', $grades), "\n"; // first key with value 'B'

Para uma chave, array_search() retorna a primeira correspondência, ou false quando não há nenhuma. A página sobre array_search explica por que você precisa comparar esse resultado com !== false.

Verificar se uma chave existe

isset($arr['key']) é a verificação comum e a mais rápida, mas retorna false quando a chave existe e guarda null. array_key_exists('key', $arr) retorna true nesse caso. Para ler com um valor padrão, o operador ?? faz as duas coisas de uma vez.

<?php
$settings = ['theme' => 'dark', 'font' => null];

var_dump(isset($settings['theme']));
var_dump(isset($settings['font']));            // null counts as not set
var_dump(array_key_exists('font', $settings)); // the key is there

$size = $settings['size'] ?? 14;               // default when missing
echo $size, "\n";

Ordenar por chave ou por valor

ksort() ordena pela chave e asort() pelo valor, os dois mantendo cada chave ligada ao seu valor. krsort() e arsort() ordenam ao contrário. Não use sort() num array associativo: ele joga as chaves fora e renumera a partir de 0.

<?php
$population = ['Tokyo' => 37, 'Delhi' => 32, 'Shanghai' => 29, 'Cairo' => 22];

ksort($population);       // A to Z by city
print_r($population);

arsort($population);      // largest value first
print_r($population);

sort($population);        // keys are lost
print_r($population);

Todas essas funções ordenam no lugar e retornam true, então $sorted = ksort($arr) dá true, não um array. Ordens personalizadas usam uasort() e uksort().

Inverter, contar e converter para JSON

Algumas linhas únicas aparecem o tempo todo com dados de chave e valor: array_flip() troca chaves e valores, array_count_values() conta quantas vezes cada valor aparece, e json_encode() transforma o array num objeto JSON.

<?php
$codes = ['red' => '#f00', 'green' => '#0f0', 'blue' => '#00f'];

print_r(array_flip($codes));           // look up a name by code

$votes = ['yes', 'no', 'yes', 'yes', 'no'];
print_r(array_count_values($votes));   // value => how many times

echo json_encode($codes), "\n";

Erro comum: ler uma chave que não existe

Ler uma chave ausente retorna null, mas o seu PHP também imprime um aviso:

<?php
$user = ['name' => 'Ada'];
echo $user['phone'];

Warning: Undefined array key "phone" in /var/www/html/index.php on line 3

Dê um valor padrão à leitura com ??, que nunca avisa, ou verifique antes com isset() quando o caso da chave ausente precisar de um ramo próprio.

<?php
$user = ['name' => 'Ada', 'email' => 'ada@example.com'];

$phone = $user['phone'] ?? 'no phone on file';
echo $phone, "\n";

if (isset($user['email'])) {
    echo "Send mail to {$user['email']}\n";
}

Dentro de uma string entre aspas duplas, coloque a consulta entre chaves, "{$user['email']}". Sem elas, o PHP só aceita a forma sem aspas "$user[email]", que é fácil de errar.