ftp_size()

A Função PHP ftp_size()

ftp_size() é uma função PHP integrada que consulta um servidor FTP sobre o tamanho, em bytes, de um único arquivo remoto. Você a utiliza quando precisa saber o tamanho de um arquivo sem precisar baixá-lo — por exemplo, para exibir uma barra de progresso, verificar se um arquivo foi alterado desde a última sincronização, ignorar arquivos vazios ou confirmar que um upload foi concluído com o tamanho esperado.

Esta página aborda a assinatura, um exemplo completo e funcional, o principal problema que atrapalha quase todos (modo passivo) e como lidar com os valores de retorno especiais.

Sintaxe

ftp_size(FTP\Connection $ftp, string $filename): int

Valor de retorno: o tamanho do arquivo em bytes como um inteiro em caso de sucesso, ou -1 em caso de erro.

Importante: ftp_size() retorna o inteiro -1 em caso de falha — ela não retorna false. Isso é diferente da maioria das outras funções FTP, portanto, sempre compare com -1, não com false.

Antes do PHP 8.1, o argumento $ftp era um resource; a partir do PHP 8.1, ele é um objeto FTP\Connection. Seu código não muda — apenas o tipo subjacente muda.

Uso Básico

Para chamar ftp_size(), você primeiro abre uma conexão com ftp_connect() e se autentica com ftp_login():

<?php

// Open a connection to the FTP server
$conn = ftp_connect('ftp.example.com');

// Log in with your credentials
ftp_login($conn, 'username', 'password');

// Turn on passive mode (see the note below — this is almost always required)
ftp_pasv($conn, true);

// Ask the server how big the file is
$size = ftp_size($conn, '/public_html/index.php');

if ($size !== -1) {
    echo "The file is {$size} bytes.";
} else {
    echo "Could not determine the file size.";
}

// Always close the connection when you are done
ftp_close($conn);

Modo Passivo: o Problema Mais Comum

Se ftp_size() continua retornando -1 mesmo que o arquivo claramente exista, a causa geralmente é o modo ativo vs. passivo, não um erro de digitação no caminho. Por trás de um firewall ou NAT (o que descreve a maioria dos servidores atualmente), o servidor FTP não consegue abrir um canal de dados de volta para o seu cliente, então o comando SIZE subjacente fica parado.

Chame ftp_pasv() após fazer login para mudar para o modo passivo, onde o seu cliente inicia todas as conexões:

<?php
ftp_login($conn, 'username', 'password');
ftp_pasv($conn, true); // do this before ftp_size(), ftp_get(), ftp_nlist(), etc.

O Modo de Transferência Afeta o Resultado

O tamanho que um servidor FTP reporta pode depender do modo de transferência atual. No modo ASCII, alguns servidores traduzem os finais de linha, portanto o tamanho reportado pode não corresponder à contagem de bytes que você obtém no modo binário. Para tamanhos precisos byte a byte, certifique-se de estar no modo binário (FTP_BINARY), que é o padrão para consultas de tamanho na maioria dos servidores e o modo que você quase sempre deseja para arquivos não textuais.

Tratamento de Erros Robusto

Como ftp_size() sinaliza falha com -1, um wrapper confiável verifica esse valor específico e avisa quando o tamanho é desconhecido:

<?php

function remoteFileSize($conn, string $path): ?int
{
    $size = ftp_size($conn, $path);

    if ($size === -1) {
        // The file is missing, the path is wrong, or the SIZE command failed.
        return null;
    }

    return $size;
}

$size = remoteFileSize($conn, '/public_html/index.php');

echo $size === null
    ? "File not found or size unavailable.\n"
    : "Size: {$size} bytes\n";

Usar null para o caso de falha evita que -1 vaze para cálculos posteriores (onde corromperia silenciosamente os totais).

Listando Tamanhos de Vários Arquivos

ftp_size() opera em um caminho por vez. Para reportar tamanhos de um diretório inteiro, combine-a com ftp_nlist(), que retorna um array de nomes de arquivos:

<?php

$files = ftp_nlist($conn, '/public_html');

if ($files !== false) {
    foreach ($files as $file) {
        $size = ftp_size($conn, $file);
        $label = $size === -1 ? 'directory or unreadable' : "{$size} bytes";
        echo "{$file}: {$label}\n";
    }
}

Observe que ftp_size() retorna -1 para diretórios, o que é uma maneira útil de distinguir arquivos de pastas em uma listagem.

Funções Relacionadas

• ftp_connect() — abre a conexão que você passa para ftp_size().
• ftp_login() — autentique-se antes de qualquer consulta de tamanho.
• ftp_pasv() — habilite o modo passivo para que ftp_size() funcione corretamente.
• ftp_nlist() — liste um diretório para obter o tamanho de vários arquivos em um loop.
• ftp_get() — baixe um arquivo depois de conhecer seu tamanho.
• ftp_close() — feche a conexão quando terminar.
• Visão geral do FTP em PHP — todas as funções FTP em um só lugar.

Conclusão

ftp_size() é a maneira mais rápida de descobrir o tamanho em bytes de um arquivo remoto sem transferi-lo. Lembre-se das duas regras que a tornam confiável: habilite o modo passivo com ftp_pasv() após o login e teste o resultado contra -1 (não false) para detectar falhas e diretórios.

Prática