ftp_nb_fget()

Comprendiendo la función PHP ftp_nb_fget()

La función ftp_nb_fget() es una función integrada de PHP que recupera un archivo de un servidor FTP y lo escribe en un archivo local usando el modo no bloqueante. Este artículo ofrece una guía completa para usarla en tus proyectos PHP.

¿Qué es ftp_nb_fget()?

La función ftp_nb_fget() recupera un archivo remoto y lo escribe en un puntero de archivo local ya abierto sin bloquear el script. No bloqueante significa que la llamada retorna inmediatamente en lugar de pausar hasta que se haya transferido el archivo completo, de modo que tu script puede seguir realizando otras tareas mientras la descarga se ejecuta en segundo plano.

Acepta cuatro parámetros (tres obligatorios y uno opcional):

La función devuelve una de tres constantes:

• FTP_FINISHED — la transferencia se completó correctamente.
• FTP_MOREDATA — la transferencia aún está en progreso; llama a ftp_nb_continue() para continuar.
• FTP_FAILED — ocurrió un error.

Bloqueante vs. no bloqueante: el equivalente bloqueante es ftp_fget(), que retorna únicamente cuando el archivo se ha transferido por completo. Usa ftp_nb_fget() cuando quieras mostrar el progreso, ejecutar otras tareas o transferir varios archivos de forma casi paralela.

Sintaxis de ftp_nb_fget()

La sintaxis de la función ftp_nb_fget() es la siguiente:

Sintaxis de ftp_nb_fget()

int ftp_nb_fget ( resource $ftp_stream , resource $handle , string $remote_file , int $mode [, int $resumepos = 0 ] )

Usa FTP_BINARY para cualquier archivo que no sea de texto (imágenes, archivos comprimidos, ejecutables) para que los bytes se copien tal cual; FTP_ASCII traduce los finales de línea y solo debe usarse para archivos de texto plano. El parámetro resumepos es útil para continuar un archivo parcialmente descargado: pasa el tamaño del archivo local para que la transferencia retome desde donde se detuvo en lugar de empezar de nuevo.

Uso de ftp_nb_fget()

Para usar la función ftp_nb_fget(), primero debes establecer una conexión con el servidor FTP usando la función ftp_connect(). Este es un ejemplo:

Uso de ftp_nb_fget()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
ftp_login($conn, 'username', 'password');

// Open a file for writing
$handle = fopen('local_file.txt', 'w');

// Initiate an asynchronous FTP operation
$result = ftp_nb_fget($conn, $handle, 'remote_file.txt', FTP_BINARY);

// Continue the asynchronous FTP operation
while ($result === FTP_MOREDATA) {
    // Do something else while waiting for the FTP operation to complete
    $result = ftp_nb_continue($conn);
}

// Check final result
if ($result === FTP_FINISHED) {
    echo "Download completed successfully.";
} else {
    echo "Download failed.";
}

fclose($handle);
ftp_close($conn);
?>

En este ejemplo, establecemos una conexión con el servidor FTP usando ftp_connect(). Luego iniciamos sesión con ftp_login(). Abrimos un archivo para escritura con fopen() e iniciamos una operación FTP asíncrona usando ftp_nb_fget(). Continuamos la operación con ftp_nb_continue() dentro de un bucle while que comprueba la constante FTP_MOREDATA. Finalmente, verificamos el resultado y cerramos el archivo y la conexión FTP.

Manejo de errores en ftp_nb_fget()

Es importante manejar los errores correctamente al usar la función ftp_nb_fget(). La función y ftp_nb_continue() devuelven constantes de estado en lugar de simples valores booleanos. Este es un ejemplo de cómo manejar errores y comprobar los estados de transferencia:

Manejo de errores en ftp_nb_fget()

<?php

// Assuming $conn is an established FTP connection
$handle = fopen('local_file.txt', 'w');
$result = ftp_nb_fget($conn, $handle, 'remote_file.txt', FTP_BINARY);

if ($result === FTP_FAILED) {
    echo "Failed to start download.\n";
} else {
    while ($result === FTP_MOREDATA) {
        $result = ftp_nb_continue($conn);
    }

    if ($result === FTP_FINISHED) {
        echo "Download completed successfully.\n";
    } else {
        echo "Download failed during transfer.\n";
    }
}

fclose($handle);
ftp_close($conn);
?>

Funciones relacionadas

• ftp_fget() — la versión bloqueante que descarga a un puntero de archivo abierto.
• ftp_nb_get() — descarga no bloqueante directamente a una ruta local (sin necesidad de fopen()).
• ftp_nb_continue() — impulsa la transferencia iniciada por ftp_nb_fget().
• ftp_nb_fput() — el equivalente no bloqueante para subir archivos.
• ftp_connect() y ftp_login() — abren y autentican la conexión.

Conclusión

La función ftp_nb_fget() recupera archivos de un servidor FTP en modo no bloqueante, permitiendo que tu script continúe con otras tareas mientras la descarga avanza. Itera siempre con ftp_nb_continue() mientras el estado sea FTP_MOREDATA, y verifica la constante final (FTP_FINISHED o FTP_FAILED) antes de considerar el archivo como completo.

Nota: La extensión FTP se considera obsoleta. Para aplicaciones modernas, se recomienda SFTP (mediante la extensión ssh2 o phpseclib) o clientes HTTP asíncronos para mayor seguridad y rendimiento.

Práctica