ftp_nb_get()

Comprendiendo la función PHP ftp_nb_get()

La función ftp_nb_get() descarga un archivo de un servidor FTP en modo no bloqueante. A diferencia de su contraparte bloqueante ftp_get(), que detiene el script hasta que se transfiere el archivo completo, ftp_nb_get() devuelve el control al programa casi de inmediato para que puedas realizar otras tareas mientras la descarga se ejecuta en segundo plano.

Esta página explica cuándo conviene usar la variante no bloqueante, detalla cada parámetro y valor de retorno, y muestra un patrón de uso completo junto con ftp_nb_continue().

Cuándo usar el modo no bloqueante

Las siglas "nb" del nombre representan non-blocking (no bloqueante). Opta por ftp_nb_get() en lugar de ftp_get() cuando:

• Quieras mostrar el progreso o mantener una interfaz de usuario responsiva mientras se descarga un archivo grande.
• Necesites intercalar otras tareas (registro de eventos, envío de señales de vida, procesamiento de datos ya descargados) durante la transferencia.
• Quieras aplicar tu propia lógica de tiempo de espera o cancelación en el bucle de sondeo.

Para una simple descarga en la que esperas el resultado, ftp_get() es más sencillo y la mejor opción. La contrapartida es que el modo no bloqueante requiere que controles la transferencia tú mismo en un bucle con ftp_nb_continue().

¿Qué es ftp_nb_get()?

La función ftp_nb_get() inicia una descarga de archivo asíncrona. Requiere cuatro parámetros:

1. ftp_stream: El identificador de conexión devuelto por ftp_connect().
2. local_file: La ruta local donde se guardará el archivo descargado.
3. remote_file: La ruta al archivo remoto en el servidor FTP.
4. mode: El modo de transferencia, ya sea FTP_ASCII o FTP_BINARY.

También acepta un quinto parámetro opcional, resumepos, que especifica la posición en el archivo remoto desde la que comenzar la descarga (por defecto es 0).

La función devuelve una de las tres constantes siguientes:

Como la función puede devolver el control antes de que la descarga finalice, casi siempre se combina con ftp_nb_continue() en un bucle que se ejecuta mientras el resultado sea FTP_MOREDATA.

Sintaxis de ftp_nb_get()

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

Sintaxis de ftp_nb_get()

int ftp_nb_get ( resource $ftp_stream , string $local_file , string $remote_file , int $mode [, int $resumepos = 0 ] )

La función ftp_nb_get() acepta cuatro parámetros obligatorios (ftp_stream, local_file, remote_file y mode) y un parámetro opcional (resumepos). El parámetro ftp_stream es el identificador de conexión devuelto por ftp_connect(). El parámetro local_file es la ruta al archivo local donde se guardará el archivo descargado. El parámetro remote_file es la ruta al archivo remoto en el servidor FTP. El parámetro mode especifica el modo de transferencia, ya sea FTP_ASCII o FTP_BINARY. El parámetro resumepos especifica la posición en el archivo remoto desde la que comenzar la descarga. Por defecto, resumepos tiene el valor 0, lo que significa que la descarga comenzará desde el principio del archivo.

Uso de ftp_nb_get()

Para usar la función ftp_nb_get(), primero debes establecer una conexión al servidor FTP mediante ftp_connect(). A continuación se muestra un ejemplo:

Uso de ftp_nb_get()

<?php

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

// Login with your FTP credentials
ftp_login($conn, 'username', 'password');

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

if ($result === FTP_FAILED) {
    echo "Failed to download file from remote server.\n";
} else {
    // 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);
    }
}

// Close the FTP connection
ftp_close($conn);

En este ejemplo, establecemos una conexión al servidor FTP mediante ftp_connect(). Luego iniciamos sesión con nuestras credenciales FTP usando ftp_login(). Iniciamos una operación FTP asíncrona con ftp_nb_get(). Continuamos la operación con ftp_nb_continue() dentro de un bucle que comprueba FTP_MOREDATA, y finalmente cerramos la conexión FTP.

Reanudación de una descarga interrumpida

El quinto parámetro opcional, resumepos, te permite continuar una descarga parcial en lugar de empezar desde el principio. Pasa el desplazamiento en bytes desde el que reanudar — habitualmente el tamaño del archivo que ya tienes en disco:

Reanudación de una descarga con resumepos

<?php

$local = 'big-archive.zip';

// If a partial file already exists, resume from where it left off.
$resumePos = file_exists($local) ? filesize($local) : 0;

$result = ftp_nb_get($conn, $local, 'big-archive.zip', FTP_BINARY, $resumePos);

while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

Esto resulta especialmente útil para archivos grandes a través de conexiones inestables, donde no quieres volver a descargar datos que ya tienes.

Manejo de errores en ftp_nb_get()

Comprueba siempre el valor de retorno. ftp_nb_get() devuelve FTP_FAILED cuando no puede iniciar (o continuar) la transferencia, y ftp_nb_continue() también puede devolver FTP_FAILED a mitad de la transmisión. Gestiona ambas situaciones:

Manejo de errores en ftp_nb_get()

<?php

$conn = ftp_connect('ftp.example.com');

if ($conn === false || !ftp_login($conn, 'username', 'password')) {
    exit("Could not connect or log in to the FTP server.\n");
}

$result = ftp_nb_get($conn, 'local_file.txt', 'remote_file.txt', FTP_BINARY);

// Drive the transfer to completion, watching for failure at every step.
while ($result === FTP_MOREDATA) {
    $result = ftp_nb_continue($conn);
}

if ($result === FTP_FINISHED) {
    echo "File downloaded successfully.\n";
} else {
    echo "Failed to download file from remote server.\n";
}

ftp_close($conn);

Al verificar la conexión, el inicio de sesión y el estado final de la transferencia por separado, puedes identificar con precisión dónde falló una operación FTP.

Funciones relacionadas

• ftp_get() — la versión bloqueante que descarga un archivo y espera a que finalice.
• ftp_nb_continue() — continúa una transferencia no bloqueante iniciada por ftp_nb_get().
• ftp_nb_fget() — como ftp_nb_get(), pero escribe en un puntero de archivo abierto en lugar de una ruta.
• ftp_connect() y ftp_login() — establecen y autentican la sesión FTP.
• ftp_close() — cierra la conexión cuando has terminado.

Conclusión

La función ftp_nb_get() descarga archivos de un servidor FTP en modo no bloqueante, permitiendo que tu script permanezca responsivo mientras se realiza una transferencia. Combínala con ftp_nb_continue() en un bucle, comprueba el valor de retorno frente a FTP_FINISHED y FTP_FAILED, y usa resumepos para recuperar descargas interrumpidas.

Práctica