ftp_nb_continue()

¿Qué es ftp_nb_continue()?

ftp_nb_continue() es una función integrada de PHP que reanuda —o continúa— una transferencia de archivos FTP no bloqueante iniciada anteriormente. El nb del nombre significa non-blocking (no bloqueante): en lugar de congelar el script hasta que se suba o descargue un archivo completo, las funciones FTP no bloqueantes devuelven el control tras cada fragmento para que el script pueda realizar otras tareas entre medias.

Esta página explica qué devuelve la función, cómo funciona el bucle de transferencia no bloqueante, cómo gestionar errores y los errores más comunes.

Cómo funcionan las transferencias no bloqueantes

Una transferencia normal como ftp_get() es bloqueante: PHP espera a que se descargue el archivo completo antes de ejecutar la siguiente línea. La familia no bloqueante — ftp_nb_get(), ftp_nb_put(), ftp_nb_fget() y ftp_nb_fput() — inicia la transferencia y retorna de inmediato. Luego se llama a ftp_nb_continue() repetidamente para avanzar la transferencia un fragmento a la vez, hasta que indica que ha finalizado.

La función devuelve una de estas tres constantes:

Nota: la función de inicio (ftp_nb_get(), etc.) devuelve el mismo conjunto de constantes, por lo que la lógica del bucle debe contemplar que la transferencia finalice ya en la primera llamada.

Sintaxis de ftp_nb_continue()

ftp_nb_continue(resource $ftp): int

Acepta un único parámetro, $ftp: el identificador de conexión devuelto por ftp_connect() o ftp_ssl_connect().

PHP 8.1+: la conexión es ahora un objeto FTP\Connection en lugar de un resource, pero el código no necesita cambios — simplemente se pasa el valor devuelto por ftp_connect().

Uso de ftp_nb_continue()

Primero se inicia una transferencia no bloqueante y luego se lleva a término con un bucle:

<?php

// Open the connection and log in
$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true); // passive mode is usually required behind firewalls

// Start a non-blocking download: local_file <- remote_file
$state = ftp_nb_get($ftp, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer forward until it finishes or fails
while ($state === FTP_MOREDATA) {
    // You can do other work here while the file streams in
    $state = ftp_nb_continue($ftp);
}

if ($state === FTP_FINISHED) {
    echo "Download complete.\n";
} else {
    echo "Download failed.\n";
}

ftp_close($ftp);

Observa el orden de los argumentos de ftp_nb_get(): es (connection, local_file, remote_file, mode) — el destino local va antes que el origen remoto.

Gestión de errores

Comprueba siempre el valor de retorno en cada iteración. Si ftp_nb_continue() devuelve FTP_FAILED, la transferencia se ha interrumpido y debes detenerla y notificarlo en lugar de entrar en un bucle infinito:

<?php

$state = ftp_nb_get($ftp, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

while ($state === FTP_MOREDATA) {
    $state = ftp_nb_continue($ftp);
}

switch ($state) {
    case FTP_FINISHED:
        echo "Transfer succeeded.\n";
        break;
    case FTP_FAILED:
        echo "Transfer failed.\n";
        break;
}

Dado que la condición del bucle es === FTP_MOREDATA, éste sale automáticamente tanto con FTP_FINISHED como con FTP_FAILED — el switch posterior indica cuál de los dos ocurrió.

Errores comunes

• Olvidar comprobar el valor de retorno de la función de inicio. Un archivo pequeño puede completarse durante la propia llamada a ftp_nb_get(), devolviendo FTP_FINISHED antes de que el bucle se ejecute. Asignar ese valor de retorno a $state (como se muestra arriba) lo gestiona correctamente.
• Llamar a ftp_nb_continue() sin una transferencia activa. Solo funciona mientras haya una operación no bloqueante pendiente; de lo contrario devuelve FTP_FAILED.
• Un bucle vacío y ajustado. El objetivo del FTP no bloqueante es realizar trabajo útil entre llamadas. Un bucle while vacío simplemente espera ocupado y no ofrece ninguna ventaja sobre el bloqueante ftp_get().
• Modo pasivo. Detrás de un cortafuegos o NAT, generalmente es necesario establecer ftp_pasv() en true antes de iniciar la transferencia.

Conclusión

ftp_nb_continue() reanuda una transferencia FTP no bloqueante iniciada con ftp_nb_get(), ftp_nb_put(), ftp_nb_fget() o ftp_nb_fput(). Llámala en un bucle mientras devuelva FTP_MOREDATA, detente en FTP_FINISHED y gestiona FTP_FAILED — así el script permanece receptivo mientras los archivos se transfieren en segundo plano.

Práctica