Manual do PHP
Anterior | Capítulo 11. Tipos | Próxima

# Arrays

Um array no PHP é atualmente um mapa ordenado. Um mapa é um tipo que relaciona valores para chaves. Este tipo é otimizado de várias maneiras, então você pode usá-lo como um array real, ou uma lista (vetor), hashtable (que é uma implementação de mapa), dicionário, coleção, pilha, fila e provavelmente mais. Como você pode ter outro array PHP como um valor, você pode facilmente simular árvores.

A explicação dessas estruturas estão além do escopo desse manual, mas você pode encontrar exemplos para cada uma dessas estruturas a seguir. Para mais informações sobre estruturas, refira-se a literatura externa sobre esses tópicos.

## Sintaxe

### Especificando com array()

Um array pode ser criado com o construtor de linguagem array(). Ele pega um certo número de pares separados por vírgula ``chave` => `valor`` .

    array( [chave =>] valor
         , ...
         )
    // chave pode ser tanto string ou um integer
    // valor pode ser qualquer coisa

`<?php $arr = array("foo" => "bar", 12 => true); echo $arr["foo"]; // bar echo $arr[12]; // 1 ?>`

A `chave` pode ser tanto um integer ou uma string. Se a chave é uma representação padrão de um integer, ele será interpretado assim (por exemplo, `"8"` será interpretado como `8`, enquanto `"08"` será interpretado como `"08"`). Não há diferença entre arrais indexados e associativos em PHP, apenas um tipo de array, que pode ter índices inteiros ou string.

O valor pode ser qualquer tipo PHP:

`<?php $arr = array("somearray" => array(6 => 5, 13 => 9, "a" => 42)); echo $arr["somearray"][6]; // 5 echo $arr["somearray"][13]; // 9 echo $arr["somearray"]["a"]; // 42 ?>`

Se omitir a chave quando fornece um novo item, o maior índice inteiro é obtido, e a nova chave será esse máximo + 1. Se você especificar uma chave que já possui um valor assimilada a ela, então o valor é sobrescrito.

`<?php // Esse array eh como ... array(5 => 43, 32, 56, "b" => 12); // ... este array array(5 => 43, 6 => 32, 7 => 56, "b" => 12); ?>`

Atenção
A partir do PHP 4.3.0, o comportamento da geração de índice descrito acima foi modificado. Agora, se você aumentar um array em que o maior índice atual for negativo, então a próxima chave criada será zero (`0`). Antes, o novo índice seria o maior índice existente mais 1, do mesmo jeito que os índices positivos.

Utilizar `TRUE` como chave será interpretado como o integer `1` na chave. Utilizando `FALSE` como chave será avaliado como o integer `0`. Usar `NULL` como chave é interpretado como uma string vazia. Usar uma string vazia como chave irá criar (ou sobrescerver) uma chave com uma string vazia e seu valor, e isto não é o mesmo que usar colchetes vazios.

Você não pode usar arrays ou objetos como chaves. Fazendo isso resultará em um alerta: `Illegal offset type`.

### Criando/modificando com a sintaxe de colchetes

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

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

    $arr[chave] = valor;
    $arr[] = valor;
    // chave tanto um integer ou string
    // valor pode ser qualquer coisa

Se `$arr` não existir ainda, ele será criado. Então isto é um meio alternativo para especificar um array. Para mudar um certo valor, apenas assimile um novo valor para um elemento especificado por sua chave. Se você quiser remover um par chave/valor, você precisa aplicar unset() nele.

`<?php $arr = array(5 => 1, 12 => 2); $arr[] = 56; // Isto eh o mesmo que $arr[13] = 56; // nesse ponto do script $arr["x"] = 42; // Isto acrescenta um novo elemento // para o array com a chave "x" unset($arr[5]); // Isto remove um elemento do array unset($arr); // E isto apaga todo o array ?>`

> Nota: Como mencionado acima, não informar a chave dentro dos colchetes, então o maior índice inteiro é obtido, e a nova chave será esse máximo + 1. Se nenhum índice inteiro existir ainda, a chave será `0` (zero). Se você especificar uma chave que já possui um valor assimilada a ela, então o valor é sobrescrito.

> Atenção
> A partir do PHP 4.3.0, o comportamento da geração de índice descrito acima foi modificado. Agora, se você aumentar um array em que o maior índice atual for negativo, então a próxima chave criada será zero (`0`). Antes, o novo índice seria o maior índice existente mais 1, do mesmo jeito que os índices positivos.

> Note que a chave inteira maior utilizada para isso não precisa necessariamente existir no array. Ele pode ter existido no array desde a última vez que o array foi indexado. Veja o seguinte exemplo:

> `<?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 chabe eh 5, em vez de zero // como voce pode ter esperado). $array[] = 6; print_r($array); // Reindexando: $array = array_values($array); $array[] = 7; print_r($array); ?>`

> O exemplo acima deve produzir a seguinte saída:

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

## Funções úteis

Há uma série de funções muito úteis para trabalhar com arrays. Veja a seção sobre arrays.

> Nota: A função unset() permite apagar chaves de um array. Esteja avisado que o array NÃO vai ser reindexado. Se você somente usa "índices inteiros comuns" (começando do zero, aumentando um a um), você pode conseguir reindexar o aaray utilizando array_values().

> `<?php $a = array( 1 => 'um', 2 => 'dois', 3 => 'três' ); unset( $a[2] ); /* irá produzir um array que pode ser definido como $a = array( 1=>'um', 3=>'três'); e NÃO $a = array( 1 => 'um', 2 => 'três'); */ $b = array_values($a); // Agora $b eh o array(1 => 'um', 2 =>'três') ?>`

foreach existe especificamente para lidar com arrays. Ele provém uma maneira fácil de percorrer qualquer array.

## Array: faça e não faça

### Porque `$foo[bar]` está errado?

Você sempre deve usar delimitadores em volta um índice de um array associativo. Por exemplo, utilizar $foo['bar'] e não $foo[bar]. Mas porque $foo[bar] está errado? Afinal de contas, você vê essa sintaxe nos scripts antigos:

`<?php $foo[bar] = 'inimigo'; echo $foo[bar]; // etc ?>`

Isto está errado, mas funciona. Então, porque está errado? A razão está neste código, que tem uma constante indefinida (bar) em vez de uma string ('bar' - repare nos delimitadores), e o PHP pode no futuro definir constantes que, infelizmente em seu código, podem ter o mesmo nome. Isto funciona, porque o PHP automaricamente converte 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.

> Nota: Isto não significa que você sempre deve delimitar as chaves nos arrays. Você não deve delimitar chaves que sejam constantes ou variáveis, porque isso vai impedir o PHP de interpretá-las.

> `<?php error_reporting(E_ALL); ini_set('display_errors', true); ini_set('html_errors', false); // Arrays simples: $array = array(1, 2); $count = count($array); for ($i = 0; $i < $count; $i++) { echo "\nVerificando $i: \n"; echo "Ruim: " . $array['$i'] . "\n"; echo "Bom: " . $array[$i] . "\n"; echo "Ruim: {$array['$i']}\n"; echo "Bom: {$array[$i]}\n"; } ?>`

> Nota: A saída do código acima deve ser:

>     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 fato:

`<?php // Vamos ver todos os erros error_reporting(E_ALL); $arr = array('fruta' => 'maçã', 'legume' => 'cenoura'); // Correto print $arr['fruta']; // maçã print $arr['legume']; // cenoura // Errado. Isto funciona mas lança um erro PHP do // nível E_NOTICE porque é utilizada uma constante indefinida (fruta) // // Repare: Quando utiliza-se a constrante indefinida fruta, o PHP assume 'fruta' print $arr[fruta]; // maçã // Agora vamos definir uma constante para demonstrar o que pode acontecer. Nós // vamos assimilar o valor 'legume' para a constante de nome fruta define('fruta', 'legume'); // Observe a diferenca agora print $arr['fruit']; // maçã print $arr[fruit]; // cenoura // O exemplo seguinte é normal dentro de uma string. Constantes não são // observadas dentro de strings e por isso nenhum E-NOTICE não é lançado aqui print "Olá $arr[fruta]"; // Olá maçã // Com uma exceção: chaves envolvendo arrays dentro de strings // ativam a checagem de constantes, como em print "Olá {$arr[fruta]}"; // Hello cenoura print "Olá {$arr['fruta']}"; // Hello maçã // E isso não funciona, resultando em um erro de interpretação do tipo: // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING' // Isso se aplica ao uso de autoglobais em strings print "Olá $arr['fruta']"; print "Olá $_GET['foo']"; // Nesse caso, use concatenacao print "Olá " . $arr['fruta']; // Olá maçã ?>`

Quando você ativa error_reporting() para mostrar erros de nível `E_NOTICE` (como configurando-a para `E_ALL`) você vê esses erros. Por padrão, error_reporting esté configurada para não mostrar esse nível de erro.

Como explicado na seção sintaxe, a chave precisa estar entre colchetes ('`[`' e '`]`'). Isto significa que você pode escrever coisas como isso:

`<?php echo $arr[algumafuncao($bar)]; ?>`

Isto é um exemplo de utilização de um valor de retorno de função como um índice de array. O PHP conhece constantes, como você deve ter visto algumas `E_*` antes.

`<?php $error_descriptions[E_ERROR] = "Um erro fatal ocorreu"; $error_descriptions[E_WARNING] = "O PHP emitiu um alarme"; $error_descriptions[E_NOTICE] = "Apenas um aviso informal"; ?>`

Note que `E_ERROR` é um identificador válido, assim como `bar` no primeiro exemplo. Mas no último exemplo seria a mesma coisa que escrevendo:

`<?php $error_descriptions[1] = "Um erro fatal ocorreu"; $error_descriptions[2] = "O PHP emitiu um alarme"; $error_descriptions[8] = "Apenas um aviso informal"; ?>`

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

Como nós mostramos nos exemplos anteriores, `$foo[bar]` funciona mas está errado. Funciona porque `bar`, na sintaxe onde é utilizada é esperada como uma expressão constante. Entretanto, nesse caso não existe constante com o nome `bar`. O PHP, hoje, assume que você quer `bar` literalmente, como a string `"bar"`, mas que você esqueceu de escrever os delimitadores.

#### Então, porque isso é tão mal?

Se em algum ponto do futuro, o time do PHP quiser acrescentar outra constante ou palavra chave, ou você mesmo introduzir outra constante na sua aplicação, você terá problemas. Por exemplo, se você já não pode utilizar as palavras `empty` e `default` dessa maneira, desde que elas são palavras reservadas especiais.

> Nota: Só para fixar, dentro de uma string delimitada por aspas, é válido não englobar índices de arrays com apóstrofos, de forma que `"$foo[bar]"` é válido. Veja os exemplos anteriores para detalhes bem como na seção sobre interpretação de variáveis em strings.

## Convertendo para array

Para qualquer dos tipos: integer, float, string, boolean e resource, se você converte um valor para um array, você obtêm um array com um elemento (de índice 0) contendo o valor escalar informado.

Se você converte um tipo object para um array, você obtêm as propriedades (variáveis membro) do objeto com elementos do array. As chaves serão o nome das variáveis membro.

Se você converter um valor `NULL` para um array, você terá um array vazio.

## Comparando

É possível comparar arrays através de array_diff() e operadorores de array.

## Exemplos

O tipo array do PHP é muito versátil, por isso temos aqui alguns exemplos para mostrar todo o poder dos arrays.

`<?php // isto $a = array( 'cor' => 'vermelha', 'sabor' => 'doce', 'forma' => 'redonda', 'nome' => 'maçã', 4 // a chave será 0 ); // isto é equivalente a acima $a['cor'] = 'vermelha'; $a['sabor'] = 'doce'; $a['forma'] = 'redonda'; $a['nome'] = 'maçã'; $a[] = 4; // a chave será 0 $b[] = 'a'; $b[] = 'b'; $b[] = 'c'; // o mesmo de array( 0 => 'a' , 1 => 'b' , 2 => 'c' ), // ou simplesmente array('a', 'b', 'c') ?>`

Exemplo 11-4. Utilizando array()
`<?php // Array como (propriedade-)mapa $map = array( 'versao' => 4, 'OS' => 'Linux', 'lang' => 'inglês', 'short_tags' => true ); // apenas chaves numéricas $array = array( 7, 8, 0, 156, -10 ); // que é o mesmo que array( 0 => 7, 1 => 8, ...) $switching = array( 10, // chave = 0 5 => 6, 3 => 7, 'a' => 4, 11, // chave = 6 (o índice máximo era 5) '8' => 2, // chave = 8 (inteiro!) '02' => 77, // chave = '02' 0 => 12 // o valor 10 será sobrescrito por 12 ); // array vazio $empty = array(); ?>`

Exemplo 11-5. Coleção
`<?php $cores = array('vermelho', 'azul', 'verde', 'amarelo'); foreach ($cores as $cor) { echo "Você gosta de $cor?\n"; } /* saida: Você gosta de vermelho? Você gosta de azul? Você gosta de verde? Você gosta de amarelo? */ ?>`

Note que atualmente não se pode mudar os valores de um array diretamente dentro de um loop. Superar essa limitação é possível da seguinte forma:

Exemplo 11-6. Coleção
`<?php foreach ($cores as $key => $cor) { // não funciona: //$cor = strtoupper($cor); //funciona: $cores[$key] = strtoupper($cor); } print_r($cores); /* saida: Array ( [0] => VERMELHO [1] => AZUL [2] => VERDE [3] => AMARELO ) */ ?>`

Este exemplo cria um array na base 1.

Exemplo 11-7. Array baseado em 1
`<?php $primeiroquarto = array(1 => 'Janeiro', 'Fevereiro', 'Março'); print_r($primeiroquarto); /* saida: Array ( [1] => 'Janeiro' [2] => 'Fevereiro' [3] => 'Março' ) */ ?>`

Exemplo 11-8. Preenchendo um array real
`<?php // preenchendo um array com todos os itens de um diretório $handle = opendir('.'); while (false !== ($file = readdir($handle))) { $files[] = $file; } closedir($handle); ?>`

Arrays são ordenados. Você pode mudar sua ordem utilizando vários funções de ordenação. Veja as funções de arrays para mais informações. Você pode contar o número de itens de um array com a função count().

Exemplo 11-9. Ordenando arrays
`<?php sort($files); print_r($files); ?>`

Porque o valor de um array pode ser qualquer coisa, isto pode ser outro array. Isto pode criar arrays recursivos e multidimensionais.

Exemplo 11-10. Arrays recursivos e multidimensionais
`<?php $fruits = array ( "frutas" => array ( "a" => "laranja", "b" => "banana", "c" => "maçã", ), "numeros" => array ( 1, 2, 3, 4, 5, 6 ), "buracos" => array ( "primeiro", 5 => "segundo", "terceiro", ), ); // Alguns exemplo de enderecos dos valores do array acima echo $fruits["buracos"][5]; // prints "segundo" echo $fruits["frutas"]["a"]; // prints "laranja" unset($fruits["buracos"][0]); // remove "primeiro" // Criando um novo array multidimensional $sucos["maca"]["verde"] = "bom"; ?>`

Você precisa estar ciente que a atribuição sempre envolve cópia de valor. Você precisa utilizar o operadore de referência para copiar um array por referência.

`<?php $arr1 = array(2, 3); $arr2 = $arr1; $arr2[] = 4; // $arr2 eh modificado, // $arr1 continua sendo apenas array(2, 3) $arr3 = &$arr1; $arr3[] = 4; // agora $arr1 e $arr3 sao os mesmos ?>`

Anterior | Principal | Próxima
Strings | Acima | Objetos