ftp_size()

La función PHP ftp_size()

ftp_size() es una función PHP integrada que consulta a un servidor FTP el tamaño, en bytes, de un único archivo remoto. Se utiliza cuando necesitas saber qué tan grande es un archivo sin descargarlo — por ejemplo, para mostrar una barra de progreso, decidir si un archivo cambió desde la última sincronización, omitir archivos vacíos o verificar que una carga se completó con el tamaño esperado.

Esta página cubre la firma, un ejemplo completo funcional, el error más común que afecta a casi todo el mundo (modo pasivo) y cómo manejar los valores de retorno especiales.

Sintaxis

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

Valor de retorno: el tamaño del archivo en bytes como un entero en caso de éxito, o -1 en caso de error.

Importante: ftp_size() devuelve el entero -1 en caso de fallo — no devuelve false. Esto es diferente de la mayoría de las otras funciones FTP, así que siempre compara contra -1, no contra false.

Antes de PHP 8.1 el argumento $ftp era un resource; a partir de PHP 8.1 es un objeto FTP\Connection. Tu código no cambia — solo lo hace el tipo subyacente.

Uso básico

Para llamar a ftp_size() primero debes abrir una conexión con ftp_connect() y autenticarte con 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 pasivo: el problema más frecuente

Si ftp_size() sigue devolviendo -1 aunque el archivo claramente existe, la causa suele ser el modo activo vs. pasivo, no un error tipográfico en la ruta. Detrás de un firewall o NAT (lo que describe a la mayoría de los servidores actuales), el servidor FTP no puede abrir un canal de datos de vuelta hacia tu cliente, por lo que el comando SIZE subyacente se bloquea.

Llama a ftp_pasv() después de iniciar sesión para cambiar al modo pasivo, donde tu cliente inicia cada conexión:

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

El modo de transferencia afecta al resultado

El tamaño que reporta un servidor FTP puede depender del modo de transferencia actual. En modo ASCII algunos servidores traducen los finales de línea, por lo que el tamaño reportado puede no coincidir con el recuento de bytes que obtienes en modo binario. Para obtener tamaños precisos byte a byte, asegúrate de estar en modo binario (FTP_BINARY), que es el predeterminado para consultas de tamaño en la mayoría de los servidores y el modo que casi siempre querrás para archivos que no son de texto.

Manejo robusto de errores

Dado que ftp_size() señala el fallo con -1, un envoltorio confiable verifica ese valor específico y avisa cuando el tamaño es desconocido:

<?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 el caso de fallo evita que -1 se filtre en cálculos posteriores (donde corrompería silenciosamente los totales).

Obtener el tamaño de muchos archivos

ftp_size() trabaja con una ruta a la vez. Para reportar los tamaños de un directorio completo, combínalo con ftp_nlist(), que devuelve un array de nombres de archivo:

<?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";
    }
}

Ten en cuenta que ftp_size() devuelve -1 para los directorios, lo cual es una forma práctica de distinguir archivos de carpetas en un listado.

Funciones relacionadas

• ftp_connect() — abre la conexión que pasas a ftp_size().
• ftp_login() — autentícate antes de cualquier consulta de tamaño.
• ftp_pasv() — habilita el modo pasivo para que ftp_size() funcione correctamente.
• ftp_nlist() — lista un directorio para obtener el tamaño de muchos archivos en un bucle.
• ftp_get() — descarga un archivo una vez que conoces su tamaño.
• ftp_close() — cierra la conexión al terminar.
• Resumen de FTP en PHP — todas las funciones FTP en un solo lugar.

Conclusión

ftp_size() es la forma más rápida de conocer el tamaño en bytes de un archivo remoto sin transferirlo. Recuerda las dos reglas que lo hacen confiable: habilita el modo pasivo con ftp_pasv() después de iniciar sesión, y compara el resultado contra -1 (no contra false) para detectar fallos y directorios.

Práctica