PHP Funções de Array

As funções de array que você vai usar no dia a dia, agrupadas pelo que fazem. Cada linha tem a assinatura, uma explicação curta, um exemplo e o resultado real, conferido no PHP 8.5 da máquina da Ana. Para aprender com calma, veja Arrays Indexados, Arrays Associativos, Funções de Array e Ordenar Arrays.

Como ler as tabelas
  • Todos os exemplos partem destas três variáveis (cada exemplo começa do zero, com os valores originais):
    <?php
    $frutas = ["maçã", "banana", "uva"];
    $notas  = ["Ana" => 9.5, "Bia" => 7, "Caio" => 8];
    $n      = [5, 3, 8, 1];
    
  • A assinatura mostra os parâmetros e, depois dos dois-pontos, o tipo do resultado: count(array $array): int recebe um array e devolve um int. Parâmetros com = valor são opcionais. &$array quer dizer que a função muda o próprio array (e precisa de uma variável).
  • Os resultados estão escritos como código PHP, no formato curto: ['maçã', 'uva'] é uma lista; ['Ana' => 9.5] mostra as chaves. Quando as chaves de uma lista "pulam" (depois de um unset ou array_filter), elas aparecem: [0 => 5, 2 => 8]. 9.5 é float, 7 é int.
  • Exemplos com duas linhas (como sort($n); e $n): a primeira executa a função, a segunda mostra como o array ficou.

Atalhos: Contar e procurar · Acrescentar e remover · Pedaços, primeiro e último · Chaves e valores · Juntar e comparar · Transformar e calcular · Ordenar · Cursor interno · Aleatório · Armadilhas


Contar e procurar

FunçãoO que fazExemploResultado
count(array $array): intQuantos itens o array tem. Arrayscount($frutas)
count([])
3
0
in_array(mixed $valor, array $array, bool $strict = false): boolO valor está no array? Use true no 3º argumento para comparar com === (sem conversão de tipo). Funções de Arrayin_array("uva", $frutas)
in_array("0", [0, 1])
in_array("0", [0, 1], true)
true
true
false
array_search(mixed $valor, array $array, bool $strict = false): int|string|falseA chave onde o valor está, ou false. Cuidado: a chave pode ser 0; compare com === false. Funções de Arrayarray_search("banana", $frutas)
array_search(8, $notas)
array_search("kiwi", $frutas)
1
'Caio'
false
array_key_exists(string|int $chave, array $array): boolA chave existe? Diferente de isset, dá true mesmo se o valor for null. Arrays Associativosarray_key_exists("Bia", $notas)
array_key_exists("x", ["x" => null])
true
true
isset($array[$chave]): boolConstrução da linguagem: a chave existe e o valor não é null? Arrays Associativosisset($notas["Ana"])
isset(["x" => null]["x"])
true
false
empty($array): boolVazio? ([], e também 0, "", null…) Booleanosempty([])
empty($frutas)
true
false
array_is_list(array $array): bool PHP 8.1+As chaves são 0, 1, 2… em ordem (uma "lista")? Funções de Arrayarray_is_list($frutas)
array_is_list($notas)
array_is_list([1 => "a"])
true
false
false

Acrescentar e remover (mudam o array)

FunçãoO que fazExemploResultado
array_push(array &$array, mixed ...$valores): intAcrescenta no fim; devolve o novo tamanho. O mesmo que $frutas[] = …. Arraysarray_push($frutas, "kiwi");
$frutas

['maçã', 'banana', 'uva', 'kiwi']
array_pop(array &$array): mixedTira e devolve o último item. Funções de Arrayarray_pop($frutas)
array_pop($frutas);
$frutas
'uva'

['maçã', 'banana']
array_shift(array &$array): mixedTira e devolve o primeiro item (as chaves numéricas são renumeradas). Funções de Arrayarray_shift($frutas)
array_shift($frutas);
$frutas
'maçã'

['banana', 'uva']
array_unshift(array &$array, mixed ...$valores): intAcrescenta no começo; devolve o novo tamanho. Funções de Arrayarray_unshift($frutas, "kiwi");
$frutas

['kiwi', 'maçã', 'banana', 'uva']
unset($array[$chave])Construção da linguagem: apaga o item. As outras chaves não são renumeradas. Arraysunset($frutas[0]);
$frutas
unset($notas["Bia"]);
$notas

[1 => 'banana', 2 => 'uva']

['Ana' => 9.5, 'Caio' => 8]
array_splice(array &$array, int $início, ?int $quantos = null, mixed $novos = []): arrayRemove $quantos itens a partir de $início (e põe $novos no lugar); devolve os removidos. Funções de Array$removidos = array_splice($frutas, 1, 1, ["pera", "kiwi"]);
$frutas

['maçã', 'pera', 'kiwi', 'uva']

Pedaços, primeiro e último

FunçãoO que fazExemploResultado
array_slice(array $array, int $início, ?int $tamanho = null, bool $manterChaves = false): arrayUm pedaço, sem mudar o original. Início negativo conta do fim. Funções de Arrayarray_slice($frutas, 1)
array_slice($frutas, 0, 2)
array_slice($frutas, -1)
['banana', 'uva']
['maçã', 'banana']
['uva']
array_chunk(array $array, int $tamanho, bool $manterChaves = false): arrayDivide em grupos de $tamanho (útil para paginação e colunas). Funções de Arrayarray_chunk([1, 2, 3, 4, 5], 2)[[1, 2], [3, 4], [5]]
array_first(array $array): mixed PHP 8.5+O primeiro valor, ou null se vazio. Antes do 8.5: $a[array_key_first($a)] ou reset($a). Funções de Arrayarray_first($frutas)
array_first($notas)
array_first([])
'maçã'
9.5
null
array_last(array $array): mixed PHP 8.5+O último valor, ou null se vazio. Antes: end($a). Funções de Arrayarray_last($frutas)
array_last($notas)
'uva'
8
array_key_first(array $array): int|string|null PHP 7.3+A primeira chave. Funções de Arrayarray_key_first($notas)'Ana'
array_key_last(array $array): int|string|null PHP 7.3+A última chave. Funções de Arrayarray_key_last($frutas)
array_key_last($notas)
2
'Caio'

Chaves e valores

FunçãoO que fazExemploResultado
array_keys(array $array, mixed $valor = ?): arrayAs chaves (só as de um valor, se informado). Arrays Associativosarray_keys($notas)
array_keys([1, 2, 1], 1)
['Ana', 'Bia', 'Caio']
[0, 2]
array_values(array $array): arrayOs valores, com chaves novas 0, 1, 2… (renumera depois de unset/array_filter). Funções de Arrayarray_values($notas)
unset($frutas[0]);
array_values($frutas)
[9.5, 7, 8]

['banana', 'uva']
array_flip(array $array): arrayTroca chaves e valores. Funções de Arrayarray_flip($frutas)['maçã' => 0, 'banana' => 1, 'uva' => 2]
array_combine(array $chaves, array $valores): arrayMonta um array com as chaves de um e os valores do outro (mesmo tamanho!). Funções de Arrayarray_combine(["a", "b"], [1, 2])
array_combine(["a"], [1, 2])
['a' => 1, 'b' => 2]
ValueError: array_combine(): Argument #1 ($keys) and argument #2 ($values) must have the same number of elements
array_fill(int $início, int $quantos, mixed $valor): arrayUm array com o mesmo valor repetido. Funções de Arrayarray_fill(0, 3, "-")['-', '-', '-']
array_fill_keys(array $chaves, mixed $valor): arrayAs chaves dadas, todas com o mesmo valor. Funções de Arrayarray_fill_keys(["Ana", "Bia"], 0)['Ana' => 0, 'Bia' => 0]
range($início, $fim, $passo = 1): arrayUma sequência de números (ou letras). forrange(1, 5)
range(0, 10, 5)
range("a", "e")
[1, 2, 3, 4, 5]
[0, 5, 10]
['a', 'b', 'c', 'd', 'e']
array_column(array $linhas, int|string|null $coluna, int|string|null $chave = null): arrayPega uma "coluna" de um array de arrays (como as linhas de um banco). Arrays Multidimensionais$p = [["id" => 7, "nome" => "Caneta"], ["id" => 9, "nome" => "Lápis"]];
array_column($p, "nome")
$p = [["id" => 7, "nome" => "Caneta"], ["id" => 9, "nome" => "Lápis"]];
array_column($p, "nome", "id")

['Caneta', 'Lápis']

[7 => 'Caneta', 9 => 'Lápis']
array_count_values(array $array): arrayConta quantas vezes cada valor aparece. Funções de Arrayarray_count_values(["uva", "maçã", "uva"])['uva' => 2, 'maçã' => 1]
array_unique(array $array): arrayRemove repetidos (mantém a primeira chave de cada). Funções de Arrayarray_unique([3, 1, 3, 2, 1])[0 => 3, 1 => 1, 3 => 2]

Experimente: mostre os nomes de quem tirou 8 ou mais, separados por vírgula (Ana, Caio). Use array_filter para escolher as notas e array_keys + implode para montar o texto.

<?php
$notas = ["Ana" => 9.5, "Bia" => 7, "Caio" => 8];
// mostre os nomes de quem tirou 8 ou mais, separados por vírgula
print_r($notas);
<?php
$notas = ["Ana" => 9.5, "Bia" => 7, "Caio" => 8];
$aprovados = array_filter($notas, fn($nota) => $nota >= 8);
echo implode(", ", array_keys($aprovados)), "\n";

Juntar e comparar

FunçãoO que fazExemploResultado
array_merge(array ...$arrays): arrayJunta arrays. Chaves numéricas são renumeradas; chaves de texto repetidas: vence a última. Funções de Arrayarray_merge($frutas, ["kiwi"])
array_merge(["a" => 1, "b" => 2], ["b" => 3])
['maçã', 'banana', 'uva', 'kiwi']
['a' => 1, 'b' => 3]
[...$a, ...$b]Operador spread: o mesmo que array_merge (desde o 8.1, também com chaves de texto). Funções Variádicas[...$frutas, "kiwi"]
[...["a" => 1], ...["a" => 2]]
['maçã', 'banana', 'uva', 'kiwi']
['a' => 2]
$a + $bUnião: acrescenta só as chaves de $b que não existem em $a (vence a primeira). Operadores["a" => 1, "b" => 2] + ["b" => 3, "c" => 4]
["x", "y"] + ["z", "w", "k"]
['a' => 1, 'b' => 2, 'c' => 4]
['x', 'y', 'k']
array_replace(array $array, array ...$trocas): arrayTroca os valores das chaves que aparecem nas trocas (sem renumerar). Funções de Arrayarray_replace($frutas, [1 => "kiwi"])['maçã', 'kiwi', 'uva']
array_diff(array $array, array ...$outros): arrayOs valores do primeiro que não estão nos outros (mantém as chaves). Funções de Arrayarray_diff($frutas, ["banana"])[0 => 'maçã', 2 => 'uva']
array_diff_key(array $array, array ...$outros): arrayO mesmo, comparando as chaves. Funções de Arrayarray_diff_key($notas, ["Bia" => 0])['Ana' => 9.5, 'Caio' => 8]
array_intersect(array $array, array ...$outros): arrayOs valores que estão em todos. Funções de Arrayarray_intersect([1, 2, 3, 4], [2, 4, 6])[1 => 2, 3 => 4]
array_intersect_key(array $array, array ...$outros): arrayOs itens cujas chaves estão em todos (bom para "pegar só estes campos"). Funções de Arrayarray_intersect_key(["nome" => "Ana", "senha" => "x", "idade" => 29], ["nome" => 0, "idade" => 0])['nome' => 'Ana', 'idade' => 29]

Transformar e calcular

Várias destas recebem uma função como argumento (o teste ou a transformação). O jeito mais curto é a arrow function fn($x) => …; veja Funções Anônimas e Arrow Functions.

FunçãoO que fazExemploResultado
array_map(?callable $função, array $array, array ...$mais): arrayAplica a função a cada valor e devolve um array novo (mantém chaves de texto se for um array só). Arrow Functionsarray_map(fn($x) => $x * 2, $n)
array_map("strtoupper", $frutas)
array_map(fn($nota) => $nota >= 8, $notas)
[10, 6, 16, 2]
['MAçã', 'BANANA', 'UVA']
['Ana' => true, 'Bia' => false, 'Caio' => true]
array_filter(array $array, ?callable $função = null, int $modo = 0): arrayMantém os itens para os quais a função devolve true (sem função: tira os "vazios"). Mantém as chaves. Arrow Functionsarray_filter($n, fn($x) => $x > 3)
array_filter([0, 1, "", "a", null])
array_filter($notas, fn($k) => $k !== "Bia", ARRAY_FILTER_USE_KEY)
[0 => 5, 2 => 8]
[1 => 1, 3 => 'a']
['Ana' => 9.5, 'Caio' => 8]
array_reduce(array $array, callable $função, mixed $inicial = null): mixed"Reduz" o array a um valor, acumulando item a item. Arrow Functionsarray_reduce($n, fn($soma, $x) => $soma + $x, 0)
array_reduce($n, fn($maior, $x) => max($maior, $x), 0)
17
8
array_walk(array &$array, callable $função): trueChama a função para cada item (valor e chave); com &$v altera o próprio array. Funções de Arrayarray_walk($notas, function (&$v, $k) { $v = "$k: $v"; });
$notas

['Ana' => 'Ana: 9.5', 'Bia' => 'Bia: 7', 'Caio' => 'Caio: 8']
array_sum(array $array): int|floatSoma dos valores. Funções de Arrayarray_sum($n)
array_sum($notas)
17
24.5
array_product(array $array): int|floatProduto (multiplicação) dos valores. Funções de Arrayarray_product([2, 3, 4])24
max(array $array) / min(array $array)Maior / menor valor (lista vazia: ValueError). int e floatmax($n)
min($notas)
max([])
8
7
ValueError: max(): Argument #1 ($value) must contain at least one element
array_reverse(array $array, bool $manterChaves = false): arrayOrdem invertida. Funções de Arrayarray_reverse($frutas)['uva', 'banana', 'maçã']
array_pad(array $array, int $tamanho, mixed $valor): arrayCompleta até o tamanho com o valor (negativo: completa no começo). Funções de Arrayarray_pad([1, 2], 4, 0)[1, 2, 0, 0]
implode(string $separador, array $array): stringJunta os valores num texto. (Apelido: join.) Funções de Stringimplode(", ", $frutas)
implode(" | ", $notas)
'maçã, banana, uva'
'9.5 | 7 | 8'
explode(string $separador, string $texto, int $limite = PHP_INT_MAX): arrayCorta um texto num array. Funções de Stringexplode(",", "maçã,banana,uva")
explode(",", "a,b,c", 2)
['maçã', 'banana', 'uva']
['a', 'b,c']
compact(string ...$nomes): arrayMonta um array a partir de variáveis com esses nomes. Funções de Array$nome = "Ana"; $idade = 29;
compact("nome", "idade")

['nome' => 'Ana', 'idade' => 29]
array_find(array $array, callable $função): mixed PHP 8.4+O primeiro valor para o qual a função dá true, ou null. Funções de Arrayarray_find($n, fn($x) => $x > 4)
array_find($n, fn($x) => $x > 100)
5
null
array_find_key(array $array, callable $função): mixed PHP 8.4+A chave do primeiro que passa no teste. Funções de Arrayarray_find_key($notas, fn($v) => $v < 8)'Bia'
array_any(array $array, callable $função): bool PHP 8.4+Algum item passa no teste? Funções de Arrayarray_any($notas, fn($v) => $v < 7.5)true
array_all(array $array, callable $função): bool PHP 8.4+Todos passam no teste? Funções de Arrayarray_all($notas, fn($v) => $v >= 7)true

Ordenar (mudam o array)

Todas as funções de ordenar mudam o próprio array e devolvem true. Para escolher: pelos valores ou pelas chaves? Manter as chaves? (a… e k… mantêm; sort/rsort/usort renumeram) Do maior para o menor? (r…) Regra própria? (u…).

FunçãoO que fazExemploResultado
sort(array &$array, int $flags = SORT_REGULAR): trueOrdena os valores, do menor ao maior, e renumera as chaves (perde os nomes!). Ordenar Arrayssort($n);
$n
sort($notas);
$notas

[1, 3, 5, 8]

[7, 8, 9.5]
rsort(array &$array, int $flags = SORT_REGULAR): trueO mesmo, do maior ao menor. Ordenar Arraysrsort($n);
$n

[8, 5, 3, 1]
asort(array &$array, int $flags = SORT_REGULAR): trueOrdena pelos valores mantendo as chaves. Ordenar Arraysasort($notas);
$notas

['Bia' => 7, 'Caio' => 8, 'Ana' => 9.5]
arsort(array &$array, int $flags = SORT_REGULAR): truePelos valores, do maior ao menor, mantendo as chaves (ranking). Ordenar Arraysarsort($notas);
$notas

['Ana' => 9.5, 'Caio' => 8, 'Bia' => 7]
ksort(array &$array, int $flags = SORT_REGULAR): trueOrdena pelas chaves. Ordenar Arrays$e = ["uva" => 3, "banana" => 5, "maçã" => 2]; ksort($e);
$e

['banana' => 5, 'maçã' => 2, 'uva' => 3]
krsort(array &$array, int $flags = SORT_REGULAR): truePelas chaves, ao contrário. Ordenar Arrayskrsort($notas);
$notas

['Caio' => 8, 'Bia' => 7, 'Ana' => 9.5]
usort(array &$array, callable $comparar): trueOrdena com a sua regra: a função recebe dois itens e devolve negativo, zero ou positivo (o <=> faz isso). Renumera. Ordenar Arrays$p = [["nome" => "Caderno", "preco" => 15.9], ["nome" => "Caneta", "preco" => 2.5]]; usort($p, fn($a, $b) => $a["preco"] <=> $b["preco"]);
array_column($p, "nome")

['Caneta', 'Caderno']
uasort(array &$array, callable $comparar): trueComo usort, mantendo as chaves. Ordenar Arraysuasort($notas, fn($a, $b) => $b <=> $a);
$notas

['Ana' => 9.5, 'Caio' => 8, 'Bia' => 7]
uksort(array &$array, callable $comparar): trueComo usort, comparando as chaves. Ordenar Arraysuksort($notas, fn($a, $b) => strlen($a) <=> strlen($b));
$notas

['Ana' => 9.5, 'Bia' => 7, 'Caio' => 8]
sort($a, SORT_STRING) / sort($a, SORT_NATURAL | SORT_FLAG_CASE)Flags: comparar como texto; ordem "natural" (foto2 antes de foto10) ignorando maiúsculas. Ordenar Arrays$a = ["foto10", "Foto2", "foto1"]; sort($a);
$a
$a = ["foto10", "Foto2", "foto1"]; sort($a, SORT_NATURAL | SORT_FLAG_CASE);
$a

['Foto2', 'foto1', 'foto10']

['foto1', 'Foto2', 'foto10']
natcasesort(array &$array): trueOrdem natural sem diferenciar maiúsculas, mantendo as chaves. Ordenar Arrays$a = ["foto10", "Foto2", "foto1"]; natcasesort($a);
$a

[2 => 'foto1', 1 => 'Foto2', 0 => 'foto10']

Cursor interno

Todo array tem um "cursor" que aponta para um item. Funções antigas o usam; hoje o foreach resolve quase tudo.

FunçãoO que fazExemploResultado
reset(array &$array): mixedVolta o "cursor" interno ao começo e devolve o primeiro valor (false se vazio). Funções de Arrayreset($frutas)'maçã'
end(array &$array): mixedLeva o cursor ao fim e devolve o último valor. Precisa de uma variável (end(explode(…)) dá Notice). Funções de Arrayend($frutas)'uva'
current() / key() / next() / prev()Valor e chave na posição do cursor; avançar; voltar. Hoje quase sempre se usa foreach. foreachnext($notas);
[key($notas), current($notas)]

['Bia', 7]

Aleatório

FunçãoO que faz
shuffle(array &$array): trueEmbaralha o array (renumera as chaves). Funções de Array
array_rand(array $array, int $quantos = 1): int|string|arraySorteia uma chave (ou um array de chaves, se $quantos > 1).

O resultado muda a cada execução:

<?php
$frutas = ["maçã", "banana", "uva"];
shuffle($frutas);
echo implode(", ", $frutas), "\n";
echo array_rand(["Ana" => 1, "Bia" => 2, "Caio" => 3]), "\n";
$ php sorteio.php
uva, banana, maçã
Caio
$ php sorteio.php
uva, maçã, banana
Bia

Armadilhas comuns

ArmadilhaO que aconteceO que fazer
if (array_search("maçã", $frutas))"maçã" está na posição 0, e 0 conta como falso no if: o teste diz "não achei".if (array_search(…) !== false), ou in_array.
sort($notas) num array associativoPerde os nomes: vira [7, 8, 9.5].asort/arsort (pelos valores) ou ksort (pelas chaves).
array_filter e depois $lista[0]As chaves originais ficam: o primeiro item pode ser a chave 2, e $lista[0] dá Undefined array key 0.array_values(array_filter(…)), ou array_first (8.5).
array_map("strtoupper", ["maçã"])Dá 'MAçã': strtoupper só mexe nas letras sem acento.mb_strtoupper: veja Acentos e mbstring e a referência de String.
array_merge com chaves numéricasAs chaves são renumeradas (IDs como chave se perdem).Use + ou array_replace para preservar as chaves.
max([]), array_combine com tamanhos diferentesValueError (o programa para).Confira count antes. Veja Mensagens de Erro.
count de um array dentro de arraycount([1, [2, 3]]) é 2; com COUNT_RECURSIVE, 4 (conta o array de dentro e os itens dele).Para somar itens de várias listas, use array_sum(array_map("count", …)).

Missão: o relatório do estoque

Missão: com as funções desta página, mostre (1) os nomes dos produtos com estoque (estoque > 0), do mais caro ao mais barato, separados por vírgula; (2) o valor total em estoque (preço × estoque de cada um, somado), formatado como R$ 239,50. Sugestão: array_filter, usort com <=>, array_column, array_map, array_sum.

<?php
$produtos = [
    ["nome" => "Caderno", "preco" => 15.90, "estoque" => 3],
    ["nome" => "Caneta", "preco" => 2.50, "estoque" => 0],
    ["nome" => "Mochila", "preco" => 89.90, "estoque" => 2],
    ["nome" => "Lápis", "preco" => 1.20, "estoque" => 10],
];
// 1) Mochila, Caderno, Lápis
// 2) Valor em estoque: R$ 239,50
<?php
$produtos = [
    ["nome" => "Caderno", "preco" => 15.90, "estoque" => 3],
    ["nome" => "Caneta", "preco" => 2.50, "estoque" => 0],
    ["nome" => "Mochila", "preco" => 89.90, "estoque" => 2],
    ["nome" => "Lápis", "preco" => 1.20, "estoque" => 10],
];
$disponiveis = array_filter($produtos, fn($p) => $p["estoque"] > 0);
usort($disponiveis, fn($a, $b) => $b["preco"] <=> $a["preco"]);
echo implode(", ", array_column($disponiveis, "nome")), "\n";
$valor = array_sum(array_map(fn($p) => $p["preco"] * $p["estoque"], $disponiveis));
echo "Valor em estoque: R$ ", number_format($valor, 2, ",", "."), "\n";
$ php missao2.php
Mochila, Caderno, Lápis
Valor em estoque: R$ 239,50

Exercícios

1. Qual função ordena $notas da maior nota para a menor mantendo os nomes?

2. O que array_filter([5, 3, 8, 1], fn($x) => $x > 3) devolve?

3. ["a" => 1, "b" => 2] + ["b" => 3, "c" => 4] dá…

Complete para pegar só os nomes de uma lista de produtos (cada um é ["nome" => …, "preco" => …]):

$nomes = ($produtos, "nome");

Complete para saber se todas as notas são maiores ou iguais a 7 (PHP 8.4+):

$todos = ($notas, fn($v) => $v >= 7);

Resumo

  • Procurar: in_array (existe?), array_search (onde? compare com !== false), array_key_exists/isset (a chave existe?), array_find (8.4).
  • Mudar: $a[] =/array_push, array_pop, array_shift, array_unshift, unset, array_splice.
  • Transformar: array_map (cada item vira outro), array_filter (escolhe; mantém as chaves), array_reduce (acumula), array_column (uma coluna).
  • Juntar: array_merge/[...$a, ...$b] (renumera), + (vence o primeiro), implode/explode (texto ↔ array).
  • Ordenar: sort/rsort (renumeram), asort/arsort (valores, mantêm chaves), ksort/krsort (chaves), usort + <=> (sua regra).