is_countable()

Introdução

A função is_countable() é uma função nativa do PHP que verifica se uma variável é contável — ou seja, se pode ser passada com segurança para count(). Um valor é contável quando é um array ou um objeto que implementa a interface Countable. A função retorna true nesses dois casos e false para todo o resto.

Ela foi introduzida no PHP 7.3 para resolver um problema real. A partir do PHP 7.2, chamar count() em um valor que não é um array ou objeto Countable emite um aviso (e no PHP 8.0 tornou-se um TypeError). Antes de is_countable() existir, era necessário escrever is_array($x) || $x instanceof Countable manualmente como proteção. Esta função torna essa verificação uma única chamada legível.

Esta página aborda a sintaxe, o valor de retorno, um exemplo funcional, o padrão comum de "contagem segura" e as armadilhas a observar.

Sintaxe

A sintaxe da função is_countable() é a seguinte:

A sintaxe PHP de is_countable()

mixed is_countable(mixed $var)

Nota: O tipo mixed requer PHP 8.0+. No PHP 7.3, a assinatura é simplesmente is_countable($var).

A função recebe um único parâmetro, $var, a variável a ser verificada.

Valor de retorno

is_countable() sempre retorna um boolean e nunca gera um erro, independentemente do que for passado:

O array vazio [] ainda é contável — ser contável diz respeito ao tipo, não se o valor contém algum elemento.

Exemplo de Uso

Aqui está um exemplo de como usar a função is_countable() em PHP:

Exemplo de is_countable() em PHP

<?php
$var1 = ["apple", "banana", "orange"];
$var2 = "hello";
$var3 = new stdClass();
$var4 = 42;
var_dump(is_countable($var1)); // output: bool(true)
var_dump(is_countable($var2)); // output: bool(false)
var_dump(is_countable($var3)); // output: bool(false)
var_dump(is_countable($var4)); // output: bool(false)

class MyCountable implements Countable {
    public function count(): int { return 5; }
}
$countableObj = new MyCountable();
var_dump(is_countable($countableObj)); // output: bool(true)
?>

Neste exemplo, definimos quatro variáveis com diferentes tipos de dados: $var1 é um array, $var2 é uma string, $var3 é um objeto simples e $var4 é um inteiro. Em seguida, usamos is_countable() para verificar cada uma delas. Apenas $var1 (um array) é contável. Note que $var3 retorna false mesmo sendo um objeto — um stdClass simples não implementa Countable. O exemplo final mostra que MyCountable, que implementa a interface Countable, é reconhecido como contável.

O padrão de "contagem segura"

O motivo mais comum para usar is_countable() é proteger uma chamada count() contra valores que podem não ser contáveis — por exemplo, dados vindos de uma API, um banco de dados ou entrada do usuário onde um campo pode ser null, uma string ou um array ausente:

Protegendo count() com is_countable()

<?php
function safeCount(mixed $value): int {
    return is_countable($value) ? count($value) : 0;
}

echo safeCount(["a", "b", "c"]), "\n"; // output: 3
echo safeCount("not an array"), "\n";  // output: 0
echo safeCount(null), "\n";            // output: 0
?>

Sem a proteção, count("not an array") lança um TypeError no PHP 8.0+. is_countable() permite retornar um valor padrão sensato em vez de travar.

Armadilhas

• Um objeto simples não é contável. is_countable(new stdClass()) retorna false. O objeto deve implementar a interface Countable para que a verificação passe.
• Strings nunca são contáveis, mesmo que tenham um comprimento. Use strlen() para caracteres, não count().
• Verifica apenas o tipo, não a profundidade. is_countable() não informa nada sobre arrays aninhados — o próprio count() aceita um argumento $mode para contagem recursiva.
• Antes do PHP 7.3, é possível replicar a verificação com is_array($var) || $var instanceof Countable.

Funções relacionadas

• count() — conta os elementos de um valor contável; é a função que is_countable() se destina a proteger.
• is_array() — verificação mais restrita apenas para o caso de array.
• is_object() — verifica se um valor é qualquer objeto (contável ou não).
• gettype() — obtém o nome do tipo de uma variável.

Conclusão

A função is_countable() é uma ferramenta útil para verificar se uma variável é contável em PHP. Ela pode ser usada para evitar erros que podem ocorrer ao tentar contar variáveis não contáveis, como strings ou objetos. Ao usar essa função, os desenvolvedores podem garantir que seu código trabalha apenas com variáveis contáveis, tornando o código mais eficiente e confiável.

Prática