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.
- 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): intrecebe um array e devolve umint. Parâmetros com= valorsão opcionais.&$arrayquer 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 umunsetouarray_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ção | O que faz | Exemplo | Resultado |
|---|---|---|---|
count(array $array): int | Quantos itens o array tem. Arrays | count($frutas)count([]) | 30 |
in_array(mixed $valor, array $array, bool $strict = false): bool | O valor está no array? Use true no 3º argumento para comparar com === (sem conversão de tipo). Funções de Array | in_array("uva", $frutas)in_array("0", [0, 1])in_array("0", [0, 1], true) | truetruefalse |
array_search(mixed $valor, array $array, bool $strict = false): int|string|false | A chave onde o valor está, ou false. Cuidado: a chave pode ser 0; compare com === false. Funções de Array | array_search("banana", $frutas)array_search(8, $notas)array_search("kiwi", $frutas) | 1'Caio'false |
array_key_exists(string|int $chave, array $array): bool | A chave existe? Diferente de isset, dá true mesmo se o valor for null. Arrays Associativos | array_key_exists("Bia", $notas)array_key_exists("x", ["x" => null]) | truetrue |
isset($array[$chave]): bool | Construção da linguagem: a chave existe e o valor não é null? Arrays Associativos | isset($notas["Ana"])isset(["x" => null]["x"]) | truefalse |
empty($array): bool | Vazio? ([], e também 0, "", null…) Booleanos | empty([])empty($frutas) | truefalse |
array_is_list(array $array): bool PHP 8.1+ | As chaves são 0, 1, 2… em ordem (uma "lista")? Funções de Array | array_is_list($frutas)array_is_list($notas)array_is_list([1 => "a"]) | truefalsefalse |
Acrescentar e remover (mudam o array)
| Função | O que faz | Exemplo | Resultado |
|---|---|---|---|
array_push(array &$array, mixed ...$valores): int | Acrescenta no fim; devolve o novo tamanho. O mesmo que $frutas[] = …. Arrays | array_push($frutas, "kiwi");$frutas | ['maçã', 'banana', 'uva', 'kiwi'] |
array_pop(array &$array): mixed | Tira e devolve o último item. Funções de Array | array_pop($frutas)array_pop($frutas);$frutas | 'uva'['maçã', 'banana'] |
array_shift(array &$array): mixed | Tira e devolve o primeiro item (as chaves numéricas são renumeradas). Funções de Array | array_shift($frutas)array_shift($frutas);$frutas | 'maçã'['banana', 'uva'] |
array_unshift(array &$array, mixed ...$valores): int | Acrescenta no começo; devolve o novo tamanho. Funções de Array | array_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. Arrays | unset($frutas[0]);$frutasunset($notas["Bia"]);$notas | [1 => 'banana', 2 => 'uva']['Ana' => 9.5, 'Caio' => 8] |
array_splice(array &$array, int $início, ?int $quantos = null, mixed $novos = []): array | Remove $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ção | O que faz | Exemplo | Resultado |
|---|---|---|---|
array_slice(array $array, int $início, ?int $tamanho = null, bool $manterChaves = false): array | Um pedaço, sem mudar o original. Início negativo conta do fim. Funções de Array | array_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): array | Divide em grupos de $tamanho (útil para paginação e colunas). Funções de Array | array_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 Array | array_first($frutas)array_first($notas)array_first([]) | 'maçã'9.5null |
array_last(array $array): mixed PHP 8.5+ | O último valor, ou null se vazio. Antes: end($a). Funções de Array | array_last($frutas)array_last($notas) | 'uva'8 |
array_key_first(array $array): int|string|null PHP 7.3+ | A primeira chave. Funções de Array | array_key_first($notas) | 'Ana' |
array_key_last(array $array): int|string|null PHP 7.3+ | A última chave. Funções de Array | array_key_last($frutas)array_key_last($notas) | 2'Caio' |
Chaves e valores
| Função | O que faz | Exemplo | Resultado |
|---|---|---|---|
array_keys(array $array, mixed $valor = ?): array | As chaves (só as de um valor, se informado). Arrays Associativos | array_keys($notas)array_keys([1, 2, 1], 1) | ['Ana', 'Bia', 'Caio'][0, 2] |
array_values(array $array): array | Os valores, com chaves novas 0, 1, 2… (renumera depois de unset/array_filter). Funções de Array | array_values($notas)unset($frutas[0]);array_values($frutas) | [9.5, 7, 8]['banana', 'uva'] |
array_flip(array $array): array | Troca chaves e valores. Funções de Array | array_flip($frutas) | ['maçã' => 0, 'banana' => 1, 'uva' => 2] |
array_combine(array $chaves, array $valores): array | Monta um array com as chaves de um e os valores do outro (mesmo tamanho!). Funções de Array | array_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): array | Um array com o mesmo valor repetido. Funções de Array | array_fill(0, 3, "-") | ['-', '-', '-'] |
array_fill_keys(array $chaves, mixed $valor): array | As chaves dadas, todas com o mesmo valor. Funções de Array | array_fill_keys(["Ana", "Bia"], 0) | ['Ana' => 0, 'Bia' => 0] |
range($início, $fim, $passo = 1): array | Uma sequência de números (ou letras). for | range(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): array | Pega 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): array | Conta quantas vezes cada valor aparece. Funções de Array | array_count_values(["uva", "maçã", "uva"]) | ['uva' => 2, 'maçã' => 1] |
array_unique(array $array): array | Remove repetidos (mantém a primeira chave de cada). Funções de Array | array_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ção | O que faz | Exemplo | Resultado |
|---|---|---|---|
array_merge(array ...$arrays): array | Junta arrays. Chaves numéricas são renumeradas; chaves de texto repetidas: vence a última. Funções de Array | array_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 + $b | Uniã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): array | Troca os valores das chaves que aparecem nas trocas (sem renumerar). Funções de Array | array_replace($frutas, [1 => "kiwi"]) | ['maçã', 'kiwi', 'uva'] |
array_diff(array $array, array ...$outros): array | Os valores do primeiro que não estão nos outros (mantém as chaves). Funções de Array | array_diff($frutas, ["banana"]) | [0 => 'maçã', 2 => 'uva'] |
array_diff_key(array $array, array ...$outros): array | O mesmo, comparando as chaves. Funções de Array | array_diff_key($notas, ["Bia" => 0]) | ['Ana' => 9.5, 'Caio' => 8] |
array_intersect(array $array, array ...$outros): array | Os valores que estão em todos. Funções de Array | array_intersect([1, 2, 3, 4], [2, 4, 6]) | [1 => 2, 3 => 4] |
array_intersect_key(array $array, array ...$outros): array | Os itens cujas chaves estão em todos (bom para "pegar só estes campos"). Funções de Array | array_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ção | O que faz | Exemplo | Resultado |
|---|---|---|---|
array_map(?callable $função, array $array, array ...$mais): array | Aplica a função a cada valor e devolve um array novo (mantém chaves de texto se for um array só). Arrow Functions | array_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): array | Mantém os itens para os quais a função devolve true (sem função: tira os "vazios"). Mantém as chaves. Arrow Functions | array_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 Functions | array_reduce($n, fn($soma, $x) => $soma + $x, 0)array_reduce($n, fn($maior, $x) => max($maior, $x), 0) | 178 |
array_walk(array &$array, callable $função): true | Chama a função para cada item (valor e chave); com &$v altera o próprio array. Funções de Array | array_walk($notas, function (&$v, $k) { $v = "$k: $v"; });$notas | ['Ana' => 'Ana: 9.5', 'Bia' => 'Bia: 7', 'Caio' => 'Caio: 8'] |
array_sum(array $array): int|float | Soma dos valores. Funções de Array | array_sum($n)array_sum($notas) | 1724.5 |
array_product(array $array): int|float | Produto (multiplicação) dos valores. Funções de Array | array_product([2, 3, 4]) | 24 |
max(array $array) / min(array $array) | Maior / menor valor (lista vazia: ValueError). int e float | max($n)min($notas)max([]) | 87ValueError: max(): Argument #1 ($value) must contain at least one element |
array_reverse(array $array, bool $manterChaves = false): array | Ordem invertida. Funções de Array | array_reverse($frutas) | ['uva', 'banana', 'maçã'] |
array_pad(array $array, int $tamanho, mixed $valor): array | Completa até o tamanho com o valor (negativo: completa no começo). Funções de Array | array_pad([1, 2], 4, 0) | [1, 2, 0, 0] |
implode(string $separador, array $array): string | Junta os valores num texto. (Apelido: join.) Funções de String | implode(", ", $frutas)implode(" | ", $notas) | 'maçã, banana, uva''9.5 | 7 | 8' |
explode(string $separador, string $texto, int $limite = PHP_INT_MAX): array | Corta um texto num array. Funções de String | explode(",", "maçã,banana,uva")explode(",", "a,b,c", 2) | ['maçã', 'banana', 'uva']['a', 'b,c'] |
compact(string ...$nomes): array | Monta 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 Array | array_find($n, fn($x) => $x > 4)array_find($n, fn($x) => $x > 100) | 5null |
array_find_key(array $array, callable $função): mixed PHP 8.4+ | A chave do primeiro que passa no teste. Funções de Array | array_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 Array | array_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 Array | array_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ção | O que faz | Exemplo | Resultado |
|---|---|---|---|
sort(array &$array, int $flags = SORT_REGULAR): true | Ordena os valores, do menor ao maior, e renumera as chaves (perde os nomes!). Ordenar Arrays | sort($n);$nsort($notas);$notas | [1, 3, 5, 8][7, 8, 9.5] |
rsort(array &$array, int $flags = SORT_REGULAR): true | O mesmo, do maior ao menor. Ordenar Arrays | rsort($n);$n | [8, 5, 3, 1] |
asort(array &$array, int $flags = SORT_REGULAR): true | Ordena pelos valores mantendo as chaves. Ordenar Arrays | asort($notas);$notas | ['Bia' => 7, 'Caio' => 8, 'Ana' => 9.5] |
arsort(array &$array, int $flags = SORT_REGULAR): true | Pelos valores, do maior ao menor, mantendo as chaves (ranking). Ordenar Arrays | arsort($notas);$notas | ['Ana' => 9.5, 'Caio' => 8, 'Bia' => 7] |
ksort(array &$array, int $flags = SORT_REGULAR): true | Ordena 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): true | Pelas chaves, ao contrário. Ordenar Arrays | krsort($notas);$notas | ['Caio' => 8, 'Bia' => 7, 'Ana' => 9.5] |
usort(array &$array, callable $comparar): true | Ordena 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): true | Como usort, mantendo as chaves. Ordenar Arrays | uasort($notas, fn($a, $b) => $b <=> $a);$notas | ['Ana' => 9.5, 'Caio' => 8, 'Bia' => 7] |
uksort(array &$array, callable $comparar): true | Como usort, comparando as chaves. Ordenar Arrays | uksort($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): true | Ordem 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ção | O que faz | Exemplo | Resultado |
|---|---|---|---|
reset(array &$array): mixed | Volta o "cursor" interno ao começo e devolve o primeiro valor (false se vazio). Funções de Array | reset($frutas) | 'maçã' |
end(array &$array): mixed | Leva o cursor ao fim e devolve o último valor. Precisa de uma variável (end(explode(…)) dá Notice). Funções de Array | end($frutas) | 'uva' |
current() / key() / next() / prev() | Valor e chave na posição do cursor; avançar; voltar. Hoje quase sempre se usa foreach. foreach | next($notas);[key($notas), current($notas)] | ['Bia', 7] |
Aleatório
| Função | O que faz |
|---|---|
shuffle(array &$array): true | Embaralha o array (renumera as chaves). Funções de Array |
array_rand(array $array, int $quantos = 1): int|string|array | Sorteia 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
| Armadilha | O que acontece | O 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 associativo | Perde 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éricas | As chaves são renumeradas (IDs como chave se perdem). | Use + ou array_replace para preservar as chaves. |
max([]), array_combine com tamanhos diferentes | ValueError (o programa para). | Confira count antes. Veja Mensagens de Erro. |
count de um array dentro de array | count([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" => …]):
Complete para saber se todas as notas são maiores ou iguais a 7 (PHP 8.4+):
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).