Entendendo a Função PHP array_column()

A função PHP array_column() extrai os valores de uma única coluna de um array multidimensional (ou de um array de objetos) e os retorna como um novo array simples. É uma das funções de array mais úteis quando você trabalha com dados que retornam de um banco de dados, um arquivo CSV ou uma API JSON como uma lista de registros, pois permite extrair apenas o campo desejado em uma única linha — sem precisar escrever um loop foreach.

Este capítulo cobre a sintaxe da função, como o parâmetro opcional index_key reordena o resultado, como ela se comporta com arrays de objetos e chaves ausentes, casos de uso comuns e armadilhas a serem observadas. Para um contexto mais amplo, veja PHP Arrays e Multidimensional Arrays.

O que é a Função array_column()?

A função array_column() é uma função nativa do PHP usada para extrair valores de um array e retorná-los como um novo array. Ela recebe dois parâmetros obrigatórios: o array do qual você deseja extrair valores e a chave (ou coluna) que deseja extrair. A função retorna um novo array contendo apenas os valores da coluna especificada.

Aqui está a sintaxe básica da função array_column():

Sintaxe da função array_column do PHP

array_column(array, column_key, [index_key]);

• array: Este é o array do qual você deseja extrair valores.
• column_key: Esta é a chave (ou coluna) que você deseja extrair.
• index_key (opcional): Esta é a chave cujo valor é usado como índice (chave) do array retornado. Passe null para column_key (desde PHP 7.0) para retornar linhas inteiras reindexadas por index_key.

A função retorna um array completamente novo; ela nunca modifica o original. Funciona em arrays cujos elementos são eles mesmos arrays ou objetos com propriedades públicas.

Como Usar a Função array_column()

Usar a função array_column() é bastante simples. Basta passar um array e a chave que você deseja extrair. Aqui está um exemplo que demonstra como usar array_column():

Exemplo PHP da função array_column

<?php

$data = [
    [
        'id' => 1,
        'name' => 'John',
        'age' => 30,
    ],
    [
        'id' => 2,
        'name' => 'Jane',
        'age' => 25,
    ],
    [
        'id' => 3,
        'name' => 'Jim',
        'age' => 35,
    ],
];

$names = array_column($data, 'name');

print_r($names);

?>

A saída deste código seria:

Array
(
  [0] => John
  [1] => Jane
  [2] => Jim
)

Neste exemplo, a função array_column() extraiu os valores da coluna name e os retornou como um novo array indexado numericamente.

Usando o Parâmetro index_key

O parâmetro index_key permite especificar uma chave para usar como índice do array retornado. Aqui está um exemplo que demonstra como usar o parâmetro index_key:

Exemplo da função PHP array_column com mais argumentos

<?php

$data = [
    [
        'id' => 1,
        'name' => 'John',
        'age' => 30,
    ],
    [
        'id' => 2,
        'name' => 'Jane',
        'age' => 25,
    ],
    [
        'id' => 3,
        'name' => 'Jim',
        'age' => 35,
    ],
];

$names = array_column($data, 'name', 'id');

print_r($names);

?>

A saída deste código seria:

Array
(
  [1] => John
  [2] => Jane
  [3] => Jim
)

Neste exemplo, array_column() extraiu os valores da coluna name e usou a coluna id como chave de cada entrada no array retornado. Esta é a forma mais rápida de construir uma tabela de consulta indexada por ID.

Retornando Linhas Inteiras com column_key null

Desde PHP 7.0 você pode passar null como column_key. A função então mantém cada linha inteira, mas reindexará o resultado por index_key. Isso é útil quando você deseja um mapa de registros por ID em vez de um único campo:

<?php

$data = [
    ['id' => 1, 'name' => 'John', 'age' => 30],
    ['id' => 2, 'name' => 'Jane', 'age' => 25],
];

$byId = array_column($data, null, 'id');

print_r($byId);

?>

Trabalhando com Arrays de Objetos

array_column() também lê propriedades públicas de objetos, então você pode usá-la em uma lista de instâncias de modelo exatamente como faria com arrays:

<?php

class User {
    public function __construct(public int $id, public string $name) {}
}

$users = [
    new User(1, 'John'),
    new User(2, 'Jane'),
];

print_r(array_column($users, 'name', 'id'));

?>

Armadilhas a Observar

• Chaves ausentes são ignoradas silenciosamente. Se uma linha não contém column_key, essa linha é simplesmente omitida do resultado — nenhum aviso é emitido. Da mesma forma, uma linha sem index_key recorre a uma chave numérica sequencial.
• Valores duplicados de index_key se sobrescrevem. Como as chaves devem ser únicas, se duas linhas compartilham o mesmo index_key, apenas a última sobrevive.
• Somente propriedades públicas de objetos são lidas. Propriedades protegidas e privadas são ignoradas, a menos que a classe implemente acessores mágicos.

Casos de Uso para array_column()

A função array_column() pode ser usada em diversas situações onde você precisa extrair valores de arrays e retorná-los como um novo array. Aqui estão alguns casos de uso comuns:

• Extrair valores de arrays multidimensionais para criar uma lista simples
• Criar um array associativo a partir de um array multidimensional
• Transformar um array multidimensional em um array unidimensional para uso em uma lista suspensa ou outro elemento de formulário

Se você também precisar transformar cada valor ao extraí-lo, use array_map(); para manter apenas as linhas que atendem a uma condição, veja array_filter().

Conclusão

A função array_column() é uma ferramenta concisa para extrair uma única coluna de arrays multidimensionais e arrays de objetos. Com o index_key opcional, você pode reindexar o resultado em uma etapa, e com um column_key null você pode construir mapas de registros completos. Usá-la em vez de um loop foreach escrito manualmente torna o código de formatação de dados mais curto e fácil de ler.

Prática