array()

Introdução

O construtor de linguagem array() cria um array PHP — um mapa ordenado que associa chaves a valores. Apesar do nome "array", um array PHP é muito mais flexível do que um array de tamanho fixo em linguagens como C ou Java: um único array pode armazenar tipos de valores mistos, crescer ou diminuir em tempo de execução e utilizar inteiros ou strings como chaves.

Esta página explica como array() funciona, os três tipos de arrays que você pode criar com ele, a sintaxe curta moderna [] e as operações do dia a dia (contagem, adição, iteração) mais utilizadas. Todos os exemplos são executáveis.

Sintaxe básica

array(value1, value2, value3, ...)
// or, since PHP 5.4, the short syntax:
[value1, value2, value3, ...]

Você também pode atribuir chaves explicitamente com a seta key => value:

array(key1 => value1, key2 => value2, ...)

Ambas as formas retornam um valor do tipo array. As duas sintaxes são intercambiáveis; a forma curta [] é preferida no código moderno.

Criando um array

Quando você não fornece chaves, o PHP atribui chaves inteiras sequenciais a partir de 0. Assim, $fruits[0] é "apple", $fruits[1] é "banana" e $fruits[2] é "orange". Este é um array indexado.

Array
(
    [0] => apple
    [1] => banana
    [2] => orange
)

Os três tipos de arrays

O PHP utiliza uma única estrutura de dados, array, para três formatos conceituais:

Arrays indexados

As chaves são inteiros atribuídos automaticamente. Use este tipo para listas ordenadas em que apenas a posição importa.

<?php
$colors = ["red", "green", "blue"];
echo $colors[1]; // green

Veja arrays indexados para mais detalhes.

Arrays associativos

Você escolhe chaves string para rotular cada valor, o que é ideal para registros e buscas.

<?php
$user = [
    "name"  => "Ada",
    "email" => "[email protected]",
    "age"   => 36,
];

echo $user["email"]; // [email protected]

Veja arrays associativos para mais detalhes.

Arrays multidimensionais

Um valor pode ser ele mesmo um array, permitindo modelar tabelas e dados aninhados.

<?php
$matrix = [
    [1, 2, 3],
    [4, 5, 6],
];

echo $matrix[1][2]; // 6

Veja arrays multidimensionais para mais detalhes.

Contando elementos

A função count() retorna quantos elementos de nível superior um array contém. Ela se combina naturalmente com array():

<?php

$fruits = array("apple", "banana", "orange");

echo count($fruits); // 3

Adicionando elementos

Para acrescentar um valor, use a sintaxe [] — é mais curta do que chamar array_push() e mais clara para um único elemento:

<?php
$fruits = ["apple", "banana"];

$fruits[] = "cherry";       // appended with the next integer key (2)
$fruits["fav"] = "mango";   // added with an explicit string key

print_r($fruits);

Array
(
    [0] => apple
    [1] => banana
    [2] => cherry
    [fav] => mango
)

Essa combinação de chaves inteiras e string em um mesmo array é perfeitamente válida — é o que torna os arrays PHP "mapas ordenados".

Iterando sobre um array

foreach é a forma idiomática de percorrer cada par chave/valor e funciona com os três tipos de arrays:

<?php
$user = ["name" => "Ada", "age" => 36];

foreach ($user as $key => $value) {
    echo "$key: $value\n";
}

name: Ada
age: 36

Veja o loop foreach para a referência completa.

Armadilhas comuns

• Chaves duplicadas sobrescrevem. [1 => "a", 1 => "b"] mantém apenas "b" — o último valor atribuído a uma chave prevalece.
• Chaves string que parecem inteiros tornam-se inteiros. ["7" => "x"] é armazenado sob a chave inteira 7, portanto $a[7] e $a["7"] acessam o mesmo elemento.
• Acessar uma chave inexistente emite um aviso e retorna null. Proteja o código com array_key_exists() ou isset() antes.
• A contagem considera apenas o nível superior. count() em um array multidimensional retorna o número de elementos externos, não a contagem total de folhas.

Boas práticas

• Prefira a sintaxe curta [] em vez de array() em código novo — é a convenção moderna.
• Use chaves string significativas para dados associativos, para que o código reflita o domínio que modela.
• Acrescente com $arr[] = ... em vez de array_push() ao adicionar um único valor.
• Ordene com a função correta para o seu tipo de chave — veja ordenação de arrays para sort(), asort(), ksort() e outras funções.

Conclusão

O construtor array() (e seu atalho []) é a base da manipulação de dados em PHP. Como um único tipo array funciona como lista indexada, mapa associativo e árvore aninhável, dominar a criação, contagem, adição e iteração desbloqueia a maior parte do conjunto de ferramentas de manipulação de dados da linguagem.

Prática