PHP Funções de Array

O PHP traz mais de 70 funções prontas para trabalhar com arrays. Você não precisa decorar nenhuma: precisa saber que elas existem, para não escrever à mão um laço que já vem pronto. Esta aula mostra as que aparecem em quase todo programa, agrupadas pelo que fazem, com a saída real de cada uma. A lista completa, para consulta, está na Referência de Funções de Array.

Nos exemplos, quando a ordem das chaves não importa, a saída usa implode(", ", …) para mostrar o array numa linha só; quando as chaves importam, usa print_r.

Antes de tudo: devolve um novo ou muda o original?

As funções de array se dividem em dois grupos, e confundir os dois é o erro número um desta aula:

<?php
$fila = ["Ana", "Bruno"];
$fila[] = "Carla";
array_push($fila, "Diego");                       // muda $fila
echo implode(", ", $fila), "\n";
array_filter($fila, fn($n) => $n !== "Ana");      // devolve um novo... que ninguém guardou
echo implode(", ", $fila), "\n";

$ php f-ref3.php
Ana, Bruno, Carla, Diego
Ana, Bruno, Carla, Diego        « a Ana continua: o resultado do array_filter foi jogado fora

O certo seria $fila = array_filter($fila, …);. Quando uma função "não fez nada", a primeira pergunta é: ela devolve um array novo que eu esqueci de guardar? A passagem "por referência" é explicada na aula Parâmetros.

Procurar

in_array: "está na lista?"

in_array(valor, array) responde true ou false. O nome é literal: "no array".

<?php
$compras = ["arroz", "feijão", "café"];
var_dump(in_array("café", $compras));
var_dump(in_array("Café", $compras));
var_dump(in_array("leite", $compras));

$codigos = [7, 12, 30];
var_dump(in_array("7", $codigos));
var_dump(in_array("7", $codigos, true));
var_dump(in_array(7, $codigos, true));

var_dump(in_array(true, ["qualquer coisa"]));
var_dump(in_array(true, ["qualquer coisa"], true));
var_dump(in_array(null, [0, 1]));

$ php f-inarray.php
bool(true)
bool(false)             « diferencia maiúsculas: "Café" não é "café"
bool(false)
bool(true)              « o texto "7" foi considerado igual ao número 7
bool(false)             « com true no fim (modo estrito), "7" não é 7
bool(true)
bool(true)              « true == "qualquer coisa"?! sem modo estrito, sim
bool(false)
bool(true)              « null == 0, sem modo estrito

Por padrão, o in_array compara com == (igualdade "frouxa", que converte tipos). O terceiro argumento, true, liga o modo estrito: a comparação passa a ser === (mesmo valor e mesmo tipo). As diferenças entre == e === estão em Comparação.

array_search: "em que posição está?"

Parecida com in_array, mas devolve a chave onde achou o valor, ou false se não achou. Também aceita o true no fim, para o modo estrito.

<?php
$compras = ["arroz", "feijão", "café"];
var_dump(array_search("café", $compras));
var_dump(array_search("arroz", $compras));
var_dump(array_search("leite", $compras));

$precos = ["café" => 18.9, "pão" => 0.75, "leite" => 5.49];
var_dump(array_search(0.75, $precos));

if (!array_search("arroz", $compras)) {
    echo "Não achei arroz?!\n";
}
$pos = array_search("arroz", $compras);
if ($pos !== false) {
    echo "Arroz está na posição $pos\n";
}

$ php f-search.php
int(2)
int(0)                  « achou, na posição 0
bool(false)             « não achou
string(4) "pão"         « num array associativo, devolve a chave com nome
Não achei arroz?!       « ERRADO: o 0 foi tratado como "falso"
Arroz está na posição 0 « certo: comparar com !== false

array_find, array_find_key, array_any, array_all PHP 8.4+

in_array procura um valor exato. Para procurar por uma condição ("o primeiro aluno com nota menor que 7"), o PHP 8.4 trouxe quatro funções que recebem uma pequena função com a pergunta. A forma fn($a) => … é uma arrow function: uma função de uma linha, escrita ali mesmo. Por enquanto leia como "para cada $a, responda isto"; ela é explicada em Funções Anônimas e Arrow Functions.

<?php
$alunos = [
    ["nome" => "Ana",   "nota" => 9.5],
    ["nome" => "Bruno", "nota" => 6.0],
    ["nome" => "Carla", "nota" => 8.5],
];
$primeiroReprovado = array_find($alunos, fn($a) => $a["nota"] < 7);
print_r($primeiroReprovado);
var_dump(array_find($alunos, fn($a) => $a["nota"] > 10));
var_dump(array_find_key($alunos, fn($a) => $a["nome"] === "Carla"));
var_dump(array_any($alunos, fn($a) => $a["nota"] < 7));
var_dump(array_all($alunos, fn($a) => $a["nota"] >= 5));
var_dump(array_all([], fn($a) => false));

$ php f-find.php
Array
(
    [nome] => Bruno         « o primeiro que atende à condição
    [nota] => 6
)
NULL                    « ninguém atende: null
int(2)                  « array_find_key devolve a chave (a Carla está no índice 2)
bool(true)              « array_any: algum aluno tem nota < 7?
bool(true)              « array_all: todos têm nota >= 5?
bool(true)              « array_all de um array vazio é sempre true

Chaves, valores, primeiro e último

<?php
$precos = ["café" => 18.9, "pão" => 0.75, "leite" => 5.49, "bolo" => 0.75];
print_r(array_keys($precos));
print_r(array_values($precos));
print_r(array_keys($precos, 0.75));
echo array_key_first($precos), " ... ", array_key_last($precos), "\n";

$ php f-keys.php
Array
(
    [0] => café             « só as chaves, numa lista nova
    [1] => pão
    [2] => leite
    [3] => bolo
)
Array
(
    [0] => 18.9             « só os valores, renumerados de 0
    [1] => 0.75
    [2] => 5.49
    [3] => 0.75
)
Array
(
    [0] => pão              « com um 2º argumento: as chaves que têm aquele valor
    [1] => bolo
)
café ... bolo

array_values é também a forma de renumerar um array cheio de buracos (depois de um unset ou de um array_filter). array_key_first e array_key_last (PHP 7.3) dão a primeira e a última chave.

array_first e array_last PHP 8.5+

Para pegar o primeiro ou o último valor, sem se preocupar com as chaves, o PHP 8.5 trouxe estas duas:

<?php
$fila = ["Ana", "Bruno", "Carla"];
var_dump(array_first($fila));
var_dump(array_last($fila));
$precos = ["café" => 18.9, "pão" => 0.75];
var_dump(array_last($precos));
var_dump(array_first([]));

$ php f-first.php
string(3) "Ana"
string(5) "Carla"
float(0.75)             « funciona com chaves de nome
NULL                    « array vazio: null, sem aviso

Em versões anteriores, use $a[array_key_last($a)], ou $a[count($a) - 1] se os índices forem 0, 1, 2… em sequência (veja Arrays Indexados).

Juntar: array_merge × +

Há duas formas de juntar arrays, e elas fazem coisas diferentes. Primeiro, com listas:

<?php
$manha = ["Ana", "Bruno"];
$noite = ["Carla", "Diego", "Elisa"];
print_r(array_merge($manha, $noite));
print_r($manha + $noite);

$ php f-merge.php
Array
(
    [0] => Ana              « array_merge: põe um depois do outro e renumera
    [1] => Bruno
    [2] => Carla
    [3] => Diego
    [4] => Elisa
)
Array
(
    [0] => Ana              « +: as chaves 0 e 1 já existiam à esquerda,
    [1] => Bruno            « então Carla e Diego foram ignorados;
    [2] => Elisa            « só a chave 2 (Elisa) era nova
)

O + não "soma" listas: ele junta por chave, e quem chegou primeiro (à esquerda) fica. Com listas, isso quase nunca é o que você quer. Com arrays associativos, os dois são úteis:

<?php
$padrao  = ["cor" => "azul", "tamanho" => "M", "fonte" => "Arial"];
$escolha = ["cor" => "verde", "tamanho" => "G"];
print_r(array_merge($padrao, $escolha));
print_r($escolha + $padrao);
print_r($padrao + $escolha);

$ php f-merge2.php
Array
(
    [cor] => verde          « array_merge: em chave repetida, vence o da DIREITA
    [tamanho] => G
    [fonte] => Arial
)
Array
(
    [cor] => verde          « +: vence o da ESQUERDA ($escolha)
    [tamanho] => G
    [fonte] => Arial        « o que faltava veio do $padrao
)
Array
(
    [cor] => azul           « invertendo, vence o $padrao
    [tamanho] => M
    [fonte] => Arial
)

Uma terceira forma, moderna, é o spread: [...$manha, ...$noite], que funciona como o array_merge. Ela é explicada em Desestruturação.

Cortar: array_slice e array_splice

Os nomes são quase iguais, mas o comportamento é oposto. array_slice ("fatia") copia um pedaço e deixa o original intacto. array_splice ("emenda") tira (e opcionalmente põe) itens no próprio array.

<?php
$fila = ["Ana", "Bruno", "Carla", "Diego", "Elisa"];
echo implode(", ", array_slice($fila, 1, 2)), "\n";
echo implode(", ", array_slice($fila, 3)), "\n";
echo implode(", ", array_slice($fila, -2)), "\n";
print_r(array_slice($fila, 2, 2));
print_r(array_slice($fila, 2, 2, true));
echo "A fila continua: ", implode(", ", $fila), "\n";

array_slice($fila, 1, 2)

A partir da posição 1, pegue 2 itens: Bruno e Carla.

array_slice($fila, 3)

Sem a quantidade: da posição 3 até o fim.

array_slice($fila, -2)

Posição negativa conta do fim: os 2 últimos. (Aqui o negativo funciona; em $fila[-1], não.)

…, true

O 4º argumento mantém as chaves originais, em vez de renumerar.

$ php f-slice.php
Bruno, Carla
Diego, Elisa
Diego, Elisa
Array
(
    [0] => Carla
    [1] => Diego
)
Array
(
    [2] => Carla            « com true, as chaves 2 e 3 foram mantidas
    [3] => Diego
)
A fila continua: Ana, Bruno, Carla, Diego, Elisa

O array_slice é o jeito de fazer paginação ("mostre os itens 11 a 20"): array_slice($produtos, 10, 10).

<?php
$fila = ["Ana", "Bruno", "Carla", "Diego", "Elisa"];
$saiu = array_splice($fila, 1, 2);
echo "Saíram: ", implode(", ", $saiu), "\n";
echo "Ficou:  ", implode(", ", $fila), "\n";
array_splice($fila, 1, 0, ["Fábio", "Gabi"]);
echo "Depois de inserir: ", implode(", ", $fila), "\n";
array_splice($fila, 0, 1, "Helena");
echo "Depois de trocar:  ", implode(", ", $fila), "\n";

$ php f-splice.php
Saíram: Bruno, Carla
Ficou:  Ana, Diego, Elisa                       « o próprio $fila mudou
Depois de inserir: Ana, Fábio, Gabi, Diego, Elisa   « tirou 0 itens na posição 1 e pôs dois
Depois de trocar:  Helena, Fábio, Gabi, Diego, Elisa  « tirou 1 na posição 0 e pôs Helena

Os argumentos do array_splice são: o array, a posição, quantos tirar, e (opcional) o que colocar no lugar. Ele devolve os itens retirados e renumera o array, sem deixar buracos (ao contrário do unset).

Pilha e fila: push, pop, shift, unshift

Quatro funções para pôr e tirar nas pontas. Todas mudam o array.

<?php
$fila = ["Ana", "Bruno"];
array_push($fila, "Carla", "Diego");
echo implode(", ", $fila), "\n";
$ultimo = array_pop($fila);
echo "pop tirou $ultimo: ", implode(", ", $fila), "\n";
$primeiro = array_shift($fila);
echo "shift tirou $primeiro: ", implode(", ", $fila), "\n";
array_unshift($fila, "Zeca");
echo "unshift pôs Zeca: ", implode(", ", $fila), "\n";
print_r($fila);

$ php f-pushpop.php
Ana, Bruno, Carla, Diego
pop tirou Diego: Ana, Bruno, Carla
shift tirou Ana: Bruno, Carla
unshift pôs Zeca: Zeca, Bruno, Carla
Array
(
    [0] => Zeca             « shift e unshift renumeram as chaves
    [1] => Bruno
    [2] => Carla
)

• Pilha (como uma pilha de pratos: o último a entrar é o primeiro a sair): array_push + array_pop.
• Fila (como a fila do banco: o primeiro a chegar é o primeiro atendido): array_push + array_shift.
• Para pôr um item no fim, $a[] = "x"; faz o mesmo que array_push e é a forma mais comum.

<?php
$compras = ["arroz", "feijão", "café", "leite", "café"];

var_dump(in_array("leite", $compras));
var_dump(array_search("café", $compras));
echo implode(", ", array_unique($compras)), "\n";
echo implode(", ", array_slice($compras, 1, 3)), "\n";
echo implode(", ", array_map(fn($item) => mb_strtoupper($item), $compras)), "\n";

Transformar: array_map, array_filter, array_reduce

Estas três recebem uma função (normalmente uma arrow function fn(…) => …) e a aplicam a cada item. Juntas, substituem a maioria dos foreach que "montam um array novo".

array_map: transformar cada item

<?php
$precos = [10.0, 25.5, 4.0];
$comAumento = array_map(fn($p) => $p * 1.1, $precos);
print_r($comAumento);
echo "Os preços originais: ", implode(", ", $precos), "\n";
$nomes = ["ana", "bruno", "carla"];
echo implode(", ", array_map(fn($n) => ucfirst($n), $nomes)), "\n";
echo implode(", ", array_map("strtoupper", $nomes)), "\n";

array_map(

"Mapeie": aplique uma função a cada item e devolva um array novo com os resultados.

fn($p) => $p * 1.1

A função: recebe um preço em $p e devolve o preço com 10% a mais. Atenção à ordem: no array_map, a função vem primeiro, o array depois.

"strtoupper"

Também dá para passar o nome de uma função pronta, entre aspas.

$ php f-map2.php
Array
(
    [0] => 11
    [1] => 28.05
    [2] => 4.4
)
Os preços originais: 10, 25.5, 4      « o array original não mudou
Ana, Bruno, Carla
ANA, BRUNO, CARLA

array_filter: ficar só com alguns

<?php
$notas = [9.5, 6.0, 8.5, 5.5, 7.0];
$aprovadas = array_filter($notas, fn($n) => $n >= 7);
print_r($aprovadas);
print_r(array_values($aprovadas));
print_r(array_filter(["Ana", "", null, "Bruno", 0, "0", false]));

$ php f-filter.php
Array
(
    [0] => 9.5
    [2] => 8.5              « as chaves originais foram mantidas: há buracos
    [4] => 7
)
Array
(
    [0] => 9.5              « array_values renumera
    [1] => 8.5
    [2] => 7
)
Array
(
    [0] => Ana              « sem função: tira tudo o que é "falso"
    [3] => Bruno            « ("", null, 0, "0" e false)
)

A função do array_filter responde true (fica) ou false (sai). Aqui a ordem é a inversa do array_map: o array primeiro, a função depois. Sim, é inconsistente; até programadores experientes conferem na documentação. E lembre: as chaves são mantidas, então use array_values se precisar de 0, 1, 2…

array_reduce: reduzir a um valor só

<?php
$notas = [9.5, 6.0, 8.5, 5.5, 7.0];
$soma = array_reduce($notas, fn($total, $n) => $total + $n, 0);
echo "Soma: $soma\n";
echo "Soma: ", array_sum($notas), "\n";
echo "Média: ", array_sum($notas) / count($notas), "\n";
echo "Maior: ", max($notas), " / Menor: ", min($notas), "\n";
echo "Produto: ", array_product([2, 3, 4]), "\n";
echo array_sum([]), "\n";

O array_reduce passa por todos os itens carregando um "acumulado". A função recebe o acumulado até ali ($total) e o item da vez ($n), e devolve o novo acumulado. O último argumento (0) é o valor inicial. Volta a volta: 0 + 9.5 = 9.5; 9.5 + 6 = 15.5; … até 36.5.

$ php f-reduce.php
Soma: 36.5
Soma: 36.5              « array_sum faz o mesmo, pronto
Média: 7.3
Maior: 9.5 / Menor: 5.5
Produto: 24             « 2 × 3 × 4
0                       « soma de um array vazio: 0

Para somas, prefira array_sum; para maior e menor, max e min. O array_reduce fica para contas que não têm função pronta.

Limpar, contar e tirar colunas

array_unique: tirar repetidos

<?php
$cidades = ["Recife", "Olinda", "Recife", "Caruaru", "Olinda"];
print_r(array_unique($cidades));
print_r(array_values(array_unique($cidades)));
print_r(array_count_values($cidades));
print_r(array_reverse(["a", "b", "c"]));

$ php f-unique.php
Array
(
    [0] => Recife           « fica a primeira ocorrência, com a chave original
    [1] => Olinda
    [3] => Caruaru
)
Array
(
    [0] => Recife
    [1] => Olinda
    [2] => Caruaru
)
Array
(
    [Recife] => 2           « array_count_values: quantas vezes cada valor aparece
    [Olinda] => 2
    [Caruaru] => 1
)
Array
(
    [0] => c                « array_reverse: de trás para frente
    [1] => b
    [2] => a
)

array_column: uma coluna da tabela

Com uma lista de fichas (aula Arrays Multidimensionais), array_column tira um campo de todas elas de uma vez.

<?php
$alunos = [
    ["nome" => "Ana",   "cidade" => "Recife", "nota" => 9.5],
    ["nome" => "Bruno", "cidade" => "Olinda", "nota" => 7.0],
    ["nome" => "Carla", "cidade" => "Recife", "nota" => 8.5],
];
print_r(array_column($alunos, "nome"));
print_r(array_column($alunos, "nota", "nome"));
echo "Média: ", array_sum(array_column($alunos, "nota")) / count($alunos), "\n";

$ php f-column.php
Array
(
    [0] => Ana
    [1] => Bruno
    [2] => Carla
)
Array
(
    [Ana] => 9.5            « com o 3º argumento, o campo "nome" vira a chave
    [Bruno] => 7
    [Carla] => 8.5
)
Média: 8.3333333333333

Repare na última linha: funções de array se encaixam umas nas outras. array_column pega as notas, array_sum soma, count conta.

range: gerar uma sequência

<?php
echo implode(" ", range(1, 10)), "\n";
echo implode(" ", range(0, 100, 25)), "\n";
echo implode(" ", range(5, 1)), "\n";
echo implode(" ", range("a", "e")), "\n";

$ php f-range.php
1 2 3 4 5 6 7 8 9 10    « de 1 a 10, incluindo os dois
0 25 50 75 100          « 3º argumento: o passo
5 4 3 2 1               « de trás para frente
a b c d e               « também com letras

range é prático com foreach (foreach (range(1, 12) as $mes)) e para montar listas de opções, como os anos num formulário.

Quando dá errado

<?php
$fila = ["Ana", "Bruno"];
$fila = array_push($fila, "Carla");
var_dump($fila);

$ php f-ref2.php
int(3)

<?php
$ultimo = array_pop(["a", "b"]);

$ php f-ref.php

Fatal error: Uncaught Error: array_pop(): Argument #1 ($array) could not be passed by reference in /home/ana/site/f-ref.php:2
Stack trace:
#0 {main}
  thrown in /home/ana/site/f-ref.php on line 2

Referência rápida

A lista completa, com todos os argumentos, está na Referência de Funções de Array. As desta aula:

Missão final

<?php
$alunos = [
    ["nome" => "Ana",   "nota" => 9.5],
    ["nome" => "Bruno", "nota" => 6.0],
    ["nome" => "Carla", "nota" => 8.5],
    ["nome" => "Diego", "nota" => 5.5],
    ["nome" => "Elisa", "nota" => 7.0],
];

$aprovados = $alunos; // troque por um array_filter
echo "Aprovados: ", "?", "\n";
echo "Média: ", "?", "\n";

<?php
$alunos = [
    ["nome" => "Ana",   "nota" => 9.5],
    ["nome" => "Bruno", "nota" => 6.0],
    ["nome" => "Carla", "nota" => 8.5],
    ["nome" => "Diego", "nota" => 5.5],
    ["nome" => "Elisa", "nota" => 7.0],
];

$aprovados = array_filter($alunos, fn($a) => $a["nota"] >= 7);
echo "Aprovados: ", implode(", ", array_column($aprovados, "nome")), "\n";
echo "Média: ", array_sum(array_column($alunos, "nota")) / count($alunos), "\n";

$ php turma.php
Aprovados: Ana, Carla, Elisa
Média: 7.3

Exercícios

Resumo

• Saiba se a função devolve um array novo (guarde o resultado) ou muda o array (só chame).
• in_array e array_search comparam com ==; passe true para o modo estrito. Teste o array_search com !== false.
• array_merge junta e renumera (nomes: vence a direita); + junta por chave (vence a esquerda).
• array_slice copia um pedaço; array_splice tira e insere no próprio array.
• push/pop no fim, unshift/shift no começo.
• array_map transforma, array_filter escolhe (mantém chaves), array_reduce resume.
• PHP 8.4: array_find, array_any, array_all. PHP 8.5: array_first, array_last.