field_count

A função mysqli_field_count() retorna o número de colunas produzidas pela consulta mais recente executada em uma conexão MySQLi. É uma maneira rápida de inspecionar a estrutura de um conjunto de resultados sem precisar manter o objeto de resultado — uma verificação útil após executar um SELECT, ou após uma query cujo número de colunas você deseja validar antes de buscar as linhas.

Este artigo aborda a sintaxe da função, seus parâmetros e valor de retorno, como ela difere da função relacionada mysqli_num_fields(), e exemplos executáveis (tanto no estilo procedural quanto no orientado a objetos).

Sintaxe

// Procedural style
mysqli_field_count(mysqli $mysql): int

// Object-oriented style
$mysqli->field_count: int   // property, read as $mysqli->field_count

Observe que a forma orientada a objetos é uma propriedade somente leitura ($mysqli->field_count), não uma chamada de método.

Como usar mysqli_field_count()

Você chama a função em uma conexão ativa logo após executar uma consulta. Não é necessário capturar o objeto de resultado — mysqli_field_count() lê o número de colunas diretamente do estado da última consulta da conexão.

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

if (mysqli_connect_errno()) {
    die("Connection failed: " . mysqli_connect_error());
}

$query = "SELECT id, name, email FROM users";
mysqli_query($mysqli, $query);

$num_fields = mysqli_field_count($mysqli);
printf("Number of columns: %d\n", $num_fields);  // Number of columns: 3

mysqli_close($mysqli);
?>

Aqui conectamos com mysqli_connect() e verificamos mysqli_connect_errno() para sair de forma limpa em caso de falha. Executamos um SELECT que retorna três colunas e, em seguida, lemos o número de colunas a partir da conexão. A saída é Number of columns: 3.

mysqli_field_count() vs mysqli_num_fields()

Essas duas funções respondem à mesma pergunta — "quantas colunas?" — mas leem a informação de lugares diferentes:

• mysqli_field_count($mysqli) recebe a conexão e informa as colunas da consulta mais recente. Use quando você não tem (ou não quer) o objeto de resultado.
• mysqli_num_fields($result) recebe um objeto de resultado retornado por mysqli_query(). Use quando você já possui o resultado e está prestes a iterá-lo.

<?php
$mysqli = mysqli_connect("localhost", "user", "pass", "shop");

$result = mysqli_query($mysqli, "SELECT id, title, price FROM products");

// From the result object:
echo mysqli_num_fields($result), "\n";   // 3

// From the connection (same last query):
echo mysqli_field_count($mysqli), "\n";  // 3

mysqli_free_result($result);
mysqli_close($mysqli);
?>

Caso de uso comum: validar o número de colunas

Um uso típico é proteger código que espera uma estrutura de resultado específica — por exemplo, confirmar que uma consulta retornou as colunas das quais você depende antes de começar a lê-las:

<?php
$mysqli = mysqli_connect("localhost", "user", "pass", "shop");

mysqli_query($mysqli, "SELECT id, name FROM categories");

if (mysqli_field_count($mysqli) === 2) {
    echo "Result has the expected 2 columns.\n";
} else {
    echo "Unexpected column count.\n";
}

mysqli_close($mysqli);
?>

Pontos de atenção

• Ela informa colunas, não linhas. Para o número de linhas afetadas por uma operação de escrita, use mysqli_affected_rows(); para uma chave de auto-incremento após uma inserção, use mysqli_insert_id().
• Ela reflete apenas a última consulta na conexão. Se você executar outra consulta no meio, o contador é atualizado.
• Uma instrução sem conjunto de resultados (INSERT/UPDATE/DELETE) deixa o contador em 0.

Conclusão

mysqli_field_count() é uma forma leve de ler o número de colunas da consulta mais recente em uma conexão MySQLi — sem precisar manter o objeto de resultado. Use-a para validar a estrutura de um resultado e prefira mysqli_num_fields() quando você já possui o objeto de resultado. Para explorar as funções relacionadas ao tratamento de resultados, consulte mysqli_query() e mysqli_fetch_field().

Prática