fetch_lengths

Neste artigo, vamos focar na função mysqli_fetch_lengths() no PHP. Ela retorna um array contendo os comprimentos de cada coluna na linha atual de um conjunto de resultados MySQLi. Vamos explicar sua sintaxe, valores de retorno, o equivalente orientado a objetos, casos de uso comuns e os problemas a evitar.

O que mysqli_fetch_lengths() faz

A função mysqli_fetch_lengths() é uma função nativa do PHP que retorna os comprimentos — em bytes — de cada valor de coluna na linha buscada mais recentemente de um conjunto de resultados MySQLi. Ela não lê a linha em si; em vez disso, informa o comprimento em bytes de cada coluna na linha em que o ponteiro de resultado está posicionado.

Isso é importante porque o MySQL armazena tudo o que envia ao cliente como bytes, e o comprimento é o tamanho real dos dados retornados — não o tamanho máximo definido para a coluna. Por exemplo, uma coluna VARCHAR(255) que contém a string "hello" reporta um comprimento de 5, não 255. Para texto multibyte (UTF-8), o comprimento é o número de bytes, que pode ser maior do que o número de caracteres.

Sintaxe

mysqli_fetch_lengths(mysqli_result $result): array|false

• $result — um objeto de resultado retornado por mysqli_query(), mysqli_store_result() ou mysqli_use_result().
• Retorna: um array indexado numericamente com os comprimentos das colunas da linha atual, ou false se nenhuma linha tiver sido buscada ainda (ou em caso de erro).

Quando usar

Você recorre a mysqli_fetch_lengths() quando o tamanho dos dados retornados importa tanto quanto os próprios dados:

• Manipulação de colunas binary / BLOB onde você precisa da contagem exata de bytes antes do processamento.
• Verificações defensivas — confirmar se uma coluna realmente retornou dados em vez de uma string vazia.
• Registro, depuração ou diagnóstico sobre a quantidade de dados que cada consulta retorna.

Como ela depende do ponteiro de linha, você deve chamá-la após um fetch (mysqli_fetch_row(), mysqli_fetch_array() ou mysqli_fetch_assoc()) e antes que o próximo fetch avance o ponteiro.

Como usar a função mysqli_fetch_lengths()

mysqli_fetch_lengths() opera no ponteiro de linha atual, então você normalmente a chama dentro de um loop de busca, logo após buscar uma linha:

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

if (!$mysqli) {
    die("Connection failed: " . mysqli_connect_error());
}

$query = "SELECT * FROM my_table";
$result = mysqli_query($mysqli, $query);

if ($result) {
    while ($row = mysqli_fetch_row($result)) {
        $lengths = mysqli_fetch_lengths($result);
        if ($lengths !== false) {
            for ($i = 0; $i < count($lengths); $i++) {
                printf("Length of column %d: %d\n", $i, $lengths[$i]);
            }
        }
    }
}

mysqli_close($mysqli);
?>

Neste exemplo, conectamos ao banco de dados e executamos uma consulta. Verificamos se a conexão e a consulta foram bem-sucedidas. Dentro do loop while, mysqli_fetch_row() avança o ponteiro de linha para a próxima linha. Em seguida, chamamos mysqli_fetch_lengths() para obter um array de comprimentos de colunas para aquela linha. A função retorna false em caso de falha, portanto verificamos o resultado antes de percorrer os comprimentos com um loop for para imprimi-los.

Estilo orientado a objetos

A mesma operação está disponível como um método no objeto mysqli_result. A maioria dos códigos modernos usa este estilo:

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

if ($mysqli->connect_errno) {
    die("Connection failed: " . $mysqli->connect_error);
}

$result = $mysqli->query("SELECT id, name FROM my_table");

if ($result) {
    while ($row = $result->fetch_row()) {
        $lengths = $result->lengths; // property, not a method call
        printf("id length: %d, name length: %d\n", $lengths[0], $lengths[1]);
    }
}

$mysqli->close();
?>

Observe que no estilo OOP os comprimentos são expostos como a propriedade somente leitura $result->lengths, não como um método.

Problemas comuns a evitar

• Chame após um fetch, não antes. Se você chamar mysqli_fetch_lengths() antes que qualquer linha tenha sido buscada, ela retorna false — o ponteiro de linha não tem nada a medir.
• Os comprimentos estão em bytes. Para texto multibyte (como UTF-8), o comprimento em bytes pode superar a contagem de caracteres. Use mb_strlen() se precisar de uma contagem de caracteres.
• Reflete apenas a linha atual. Chamá-la novamente após buscar a próxima linha fornece os comprimentos dessa nova linha, portanto armazene o array se precisar dos valores anteriores.
• Colunas NULL reportam um comprimento de 0, igual a uma string vazia — combine com o valor buscado se precisar distingui-los.

Funções relacionadas

• mysqli_fetch_row() — busca uma linha como um array numérico (comumente usada em conjunto com esta função).
• mysqli_fetch_array() e mysqli_fetch_assoc() — busca uma linha como um array numérico/associativo ou associativo.
• mysqli_fetch_fields() — obtém metadados (nome, tipo, comprimento máximo) sobre cada coluna.
• mysqli_field_count() — obtém o número de colunas na última consulta.

Conclusão

A função mysqli_fetch_lengths() é uma ferramenta prática para recuperar o tamanho em bytes de cada coluna na linha atual de um conjunto de resultados MySQLi. Lembre-se de que ela opera na linha buscada mais recentemente, retorna comprimentos em bytes e produz false quando nenhuma linha está disponível — ter essas regras em mente permite integrá-la de forma confiável nos seus fluxos de trabalho com banco de dados.

Prática