Especificando com array()

Um array pode ser criado com o construtor de linguagem array(). Ele leva qualquer quantidade de pares separados por vírgula chave => valor como argumentos.

array(
    chave  => valor,
    chave2 => valor2,
    chave3 => valor3,
    ...
)

A vírgula após o último elemento do array é opcional e pode ser omitida. Isso geralmente é feito para arrays em uma única linha, por exemplo, array(1, 2) é preferível em vez de array(1, 2, ). Para arrays escritos em várias linhas, por outro lado, a vírgula à direita do último elemento é usada frequentemente, para permitir a adição de forma simples de novos elementos ao final.

Nota:

Existe uma sintaxe curta que substitui array() por [].

A chave pode ser um int ou uma string. O valor pode ser de qualquer tipo.

Adicionalmente, as seguintes coerções ocorrerão a chave:

• strings contendo quaisquer ints válidos, que não sejam precedidos do sinal de +, serão convertidos para o tipo int. Por exemplo, a chave"8" será, na verdade, armazenada como 8. Entretanto, "08" não será convertido, por não ser um inteiro decimal válido.
• floats também são convertidos para ints, isso significa que a parte fracionária será removida. Por exemplo, a chave 8.7 será na verdade armazenada como 8.
• bools são convertidos para ints, igualmente, por exemplo, a chave true, será na verdade armazenada como 1 e a chave false como 0.
• null será convertido para uma string vazia, por exemplo, a chave null na verdade será armazenada como "".
• arrays e objects não podem ser usados como chaves. Fazer isso resultará em um aviso: Illegal offset type.

Se vários elementos na declaração do array utilizam a mesma chave, apenas o último será utilizado, enquanto todos os outros serão sobrescritos.

array(1) {
  [1]=>
  string(1) "d"
}

As chaves dos arrays no PHP podem conter, ao mesmo tempo, int e string, porque o PHP não faz distinção entre arrays indexados e associativos.

array(4) {
  ["foo"]=>
  string(3) "bar"
  ["bar"]=>
  string(3) "foo"
  [100]=>
  int(-100)
  [-100]=>
  int(100)
}

A key é opcional. Se não for especificada, o PHP utilizará o incremento da chave do tipo int com maior valor utilizado.

array(4) {
  [0]=>
  string(3) "foo"
  [1]=>
  string(3) "bar"
  [2]=>
  string(5) "hello"
  [3]=>
  string(5) "world"
}

É possível especificar a chave somente para alguns elementos e omití-las para outros:

array(4) {
  [0]=>
  string(1) "a"
  [1]=>
  string(1) "b"
  [6]=>
  string(1) "c"
  [7]=>
  string(1) "d"
}

array(7) {
  [1]=>
  string(1) "g"
  [-1]=>
  string(1) "d"
  ["01"]=>
  string(1) "e"
  ["1.5"]=>
  string(1) "f"
  [0]=>
  string(1) "h"
  [""]=>
  string(1) "j"
  [2]=>
  string(1) "l"
}

array(2) {
  [-5]=>
  int(1)
  [-4]=>
  int(2)
}

array(2) {
  [-5]=>
  int(1)
  [0]=>
  int(2)
}

Acessando elementos do array com colchetes

Elementos do array podem ser acessados utilizando a sintaxe array[chave].

string(3) "bar"
int(24)
string(3) "foo"

Nota:

Anteriormente ao PHP 8.0.0, chaves e colchetes podiam ser utilizados para acessar elementos de um array (por exemplo, $array[42] e $array{42} irão fazer a mesma coisa que o exemplo anterior). O acesso por chaves foi descontinuado a partir do PHP 7.4.0 e não é mais suportado a partir do PHP 8.0.0.

Nota:

Tentativas de acesso a uma chave de array que não foi definida é o mesmo que acessar qualquer outra variável indefinida: uma mensagem de erro de nível E_WARNING (E_NOTICE anteriormente ao PHP 8.0.0) será emitida, e o resultado será null.

Nota:

Acessar um array através de uma chave que não é string retorna null. Anteriormente ao PHP 7.4.0 não era emitida uma mensagem. A partir do PHP 7.4.0 emite um E_NOTICE; e a partir do PHP 8.0.0 é emitido um E_WARNING.

Criando/modificando com a sintaxe de colchetes

Você pode também modificar um array existente explicitamente assimilando valores a ele.

Isto é feito apenas assimilando valores para o array enquanto especifica a chave em colchetes. Você pode omitir a chave, colocando um par vazio de colchetes ([]).

$arr[chave] = valor;
$arr[] = valor;
// chave pode ser tanto um int quanto uma string
// valor pode ser qualquer valor de qualquer tipo

Se $arr ainda não existir ou estiver definido como null ou false, ele será criado, por isso também é uma alternativa para criação de um array. Entretanto, essa prática é desencorajada por que se $arr conter algum valor (por exemplo, uma string de uma variável de requisição), então este valor permanecerá e o [] funcionará como um operador de acesso a string. Sempre será recomendado a inicialização de uma variável por atribuição direta.

Nota: A partir do PHP 7.1.0, aplicar um operador de índice vazio a uma string lança um erro fatal. Antes, a string era silenciosamente convertida em um array.

Nota: A partir do PHP 8.1.0, criar um novo array a partir do valor false foi descontinuado. Criar um array a partir de null e valores indefinidos ainda é permitido.

Para mudar um certo valor, apenas atribua um novo valor a um elemento especificado por sua chave. Se a intenção for remover um par de chave/valor, é necessário aplicar a função unset() na chave.

Nota:

Como mencionado acima, se nenhuma chave for especificada, o maior índice int é obtido, e a nova chave será esse máximo + 1. Se nenhum índice int existir ainda, a chave será 0 (zero).

Note que a chave inteira de maior valor utilizada não precisa necessariamente existir no array. Ele precisa ter existido no array em algum momento desde a última reindexação do array. Veja o exemplo a seguir:

<?php
// Criando um array normal
$array = array(1, 2, 3, 4, 5);
print_r($array);

// Agora apagando todos os itens, mas deixando o array intacto:
foreach ($array as $i => $value) {
unset($array[$i]);
}
print_r($array);

// Acrescentando um item (note que a chave é 5, em vez de zero).
$array[] = 6;
print_r($array);

// Reindexando:
$array = array_values($array);
$array[] = 7;
print_r($array);
?>

O exemplo acima produzirá:

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
    [3] => 4
    [4] => 5
)
Array
(
)
Array
(
    [5] => 6
)
Array
(
    [0] => 6
    [1] => 7
)

Desconstruindo arrays

Arrays podem ser desconstruídos utilizando [] (a partir do PHP 7.1.0) ou list(). Esses constructos podem ser utilizados para desconstruir o array em variáveis distintas.

A desconstrução de arrays pode ser utilizada no foreach para desconstruir um array multidimensional enquanto o percorre.

Elementos de arrays serão ignorados se a variável não for providenciada. A desconstrução de arrays sempre inicia no índice 0.

A partir do PHP 7.1.0, é possível desconstruir arrays associativos. Isto permite fácil seleção do elemento correto de uma forma indexada numericamente dado que os índices podem ser especificados.

A desconstrução de arrays pode ser utilizada para trocar duas variáveis.

Nota:

O operador de espalhamento (...) não é suportado em atribuições.

Nota:

Tentar acessar uma chave indefinida têm o mesmo efeito de acessar uma variável indefinida: um aviso E_WARNING (E_NOTICE anteriormente ao PHP 8.0.0) será emitido, e o resultado será null.

Nota:

A desconstrução de um valor escalar atribui null a todas as variáveis.

Porque $foo[bar] está errado?

Sempre utilize delimitadores em torno dos índices do array. Por exemplo, $foo['bar'] está correto, enquanto que $foo[bar], não está. Mas porque? É comum encontrar essa sintaxe em scripts antigos:

Isto está errado, mas funciona. A razão é que este código possui uma constante indefinida (bar) em vez de uma string ('bar' - repare nas aspas simples). Isto funciona, porque o PHP converte automaticamente uma string base (uma string não delimitada que não corresponde a nenhum símbolo conhecido) em uma string que contém a string base. Por exemplo, se não existir uma constante definida com o nome bar, então o PHP irá substituí-la pela string 'bar' e usá-la.

Isto não significa que deve-se sempre delimitar as chaves. Não delimite chaves que sejam constantes ou variáveis, porque isso impedirá o PHP de interpretá-las.

O exemplo acima produzirá:

Verificando 0:
Notice: Undefined index:  $i in /path/to/script.html on line 9
Ruim:
Bom: 1
Notice: Undefined index:  $i in /path/to/script.html on line 11
Ruim:
Bom: 1

Verificando 1:
Notice: Undefined index:  $i in /path/to/script.html on line 9
Ruim:
Bom: 2
Notice: Undefined index:  $i in /path/to/script.html on line 11
Ruim:
Bom: 2

Mais exemplos para demonstrar esse comportamento:

Como especificado na seção sobre sintaxe, o que estiver entre os colchetes ('[' e ']'), precisa ser uma expressão. Isso significa que códigos como estes funcionam:

Isto é um exemplo de utilização de um valor de retorno de função como um índice de array. O PHP também aceita constantes:

Observe que E_ERROR também é um identificador válido, assim como bar no primeiro exemplo. Mas no último exemplo seria, na verdade, o mesmo que escrever:

porque E_ERROR é igual a 1, e assim por diante.