count()

A função count() é uma função nativa do PHP que retorna o número de elementos em um array. Ela também pode contar um object se esse object implementar a interface Countable. É uma das funções de array mais utilizadas em PHP, geralmente para descobrir quantos itens uma lista contém antes de iterá-la, paginá-la ou validá-la.

Este capítulo aborda a sintaxe, o modo de contagem recursiva opcional, como a count() se comporta em objects e valores extremos, e os erros mais comuns a evitar.

Sintaxe da Função count()

A sintaxe da função count() é simples. Ela aceita um argumento, que é o array ou object que você deseja contar. A função retorna um inteiro representando o número de elementos ou propriedades.

<?php

count(mixed $array_or_object, int $mode = COUNT_NORMAL): int

Nota: A assinatura tipada acima reflete o PHP 8.0+. No PHP 8.0+, passar um tipo não contável (como uma string ou inteiro) lança um ValueError. Versões mais antigas do PHP não possuem dicas de tipo estritas, mas funcionam de forma idêntica. Nota: sizeof() é um alias legado de count() e se comporta de forma idêntica.

O segundo argumento, $mode, é opcional e especifica como a função count() deve se comportar. Ele aceita dois valores possíveis:

• COUNT_NORMAL: Este é o modo padrão e se comporta da mesma forma que a função count() sem o parâmetro $mode. Ele simplesmente conta o número de elementos no array ou propriedades no object.
• COUNT_RECURSIVE: Este modo conta recursivamente os elementos em arrays e objects aninhados.

<?php

$data = array('apple', array('banana', 'cherry'));

echo count($data);                  // Output: 2
echo count($data, COUNT_RECURSIVE); // Output: 4

Com COUNT_NORMAL (o padrão), count($data) retorna 2: o array externo contém dois elementos — a string 'apple' e o array interno. Com COUNT_RECURSIVE, o PHP também conta os elementos dentro de cada array aninhado, retornando 4: 'apple', o array interno em si, 'banana' e 'cherry'. Use o modo recursivo somente quando realmente precisar da contagem total em todos os níveis de aninhamento — ele percorre toda a estrutura e é mais lento em arrays grandes e profundamente aninhados.

Exemplos de Uso da Função count()

Vamos ver alguns exemplos práticos de como a função count() pode ser usada para contar os elementos em um array e as propriedades em um object.

Exemplo 1: Contando os Elementos em um Array

Contando os Elementos em um Array em PHP

Neste exemplo, temos um array chamado $fruits contendo três elementos. A função count() retorna 3, representando o número total de itens no array.

Exemplo 2: Contando as Propriedades em um Object

Contando as Propriedades em um Object em PHP

<?php

class Person implements Countable
{
    public $name;
    public $age;

    public function count()
    {
        return count(get_object_vars($this));
    }
}

$person = new Person();
$person->name = 'John';
$person->age = 30;

echo count($person); // Output: 2

Neste exemplo, temos uma classe simples chamada Person com duas propriedades públicas, $name e $age. Criamos uma nova instância da classe Person e definimos os valores de suas propriedades. Como a classe implementa a interface Countable, chamar count($person) invoca o método personalizado count(), que retorna 2. Isso demonstra como o comportamento de count() pode ser personalizado para objects.

Nota: Sem a interface Countable, passar um object comum para count() gera um TypeError no PHP 8.0+. count() não conta as propriedades de um object automaticamente — se quiser isso, use count(get_object_vars($obj)) diretamente.

Erros Comuns e Casos Extremos

Alguns comportamentos da count() costumam surpreender desenvolvedores:

• Contar null ou escalares lança exceção no PHP 8. No PHP 7.2–7.4, count(null) emitia um aviso e retornava 0, e contar um escalar não contável retornava 1. Desde o PHP 8.0, passar qualquer valor não contável (null, uma string, um inteiro) lança um TypeError. Verifique o valor primeiro quando ele pode não ser um array.
• count() não é uma função de comprimento de string. Para contar os caracteres em uma string, use strlen(), não count().
• Apenas o nível superior é contado por padrão. Como mostrado acima, arrays aninhados contam como um único elemento, a menos que você passe COUNT_RECURSIVE.

<?php

$value = null;

// Safe even when $value is not an array:
$total = is_array($value) ? count($value) : 0;

echo $total; // Output: 0

Use is_array() para garantir que um valor é contável antes de chamar count() em dados cujo tipo você não controla (por exemplo, JSON decodificado ou uma linha de banco de dados).

Funções Relacionadas

• array_count_values() — contar quantas vezes cada valor distinto aparece em um array.
• in_array() — verificar se um valor existe em um array.
• array_push() — adicionar elementos a um array (cujo tamanho você pode depois verificar com count()).
• Arrays multidimensionais — onde COUNT_RECURSIVE é mais útil.
• Loop foreach — iterar sobre os itens que você acabou de contar.

Conclusão

A função count() é uma ferramenta pequena, mas essencial para trabalhar com arrays em PHP. Use-a para determinar o tamanho de uma lista antes de iterá-la ou paginá-la, recorra a COUNT_RECURSIVE quando precisar de uma contagem completa em arrays aninhados, e lembre-se de que no PHP 8.0+ você deve passar um array real (ou um object Countable) — proteja valores incertos com is_array() primeiro. Com essas regras em mente, count() é uma forma confiável e legível de medir as estruturas de dados das quais o seu código depende.

Prática