ftp_nb_fput()

Comprendiendo la función PHP ftp_nb_fput()

La función ftp_nb_fput() es una función PHP integrada que sube un archivo a un servidor FTP usando modo no bloqueante. "No bloqueante" significa que la función devuelve el control a tu script antes de que termine la transferencia, de modo que puedes ejecutar otro código (actualizar una barra de progreso, procesar otra tarea) mientras la subida sigue en curso. Este artículo explica los parámetros, los valores de retorno y un patrón de trabajo completo para usarla en tus proyectos PHP.

La función equivalente bloqueante es ftp_fput(), que simplemente espera hasta que el archivo completo sea subido. Usa ftp_nb_fput() solo cuando necesites realizar trabajo durante la transferencia.

¿Qué es ftp_nb_fput()?

La función ftp_nb_fput() sube un archivo a un servidor FTP usando modo no bloqueante. Acepta cuatro parámetros obligatorios y uno opcional:

1. ftp_stream: El identificador de conexión devuelto por ftp_connect().
2. remote_file: La ruta al archivo remoto en el servidor FTP.
3. handle: Un puntero de archivo abierto al archivo local.
4. mode: El modo de transferencia, ya sea FTP_ASCII o FTP_BINARY.
5. startpos (opcional): La posición en el archivo remoto desde la que se iniciará la subida. Por defecto es 0.

La función devuelve una de las siguientes constantes: FTP_SUCCESS (subida completada), FTP_MOREDATA (se necesitan leer más datos) o FTP_FAILED (ocurrió un error).

Sintaxis de ftp_nb_fput()

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

int ftp_nb_fput ( resource $ftp_stream , string $remote_file , resource $handle , int $mode [, int $startpos = 0 ] )

La función toma cuatro parámetros obligatorios (ftp_stream, remote_file, handle y mode) y un parámetro opcional (startpos). El parámetro ftp_stream es el identificador de conexión devuelto por ftp_connect(). El parámetro remote_file es la ruta al archivo remoto en el servidor FTP. El parámetro handle es un puntero de archivo abierto en el sistema de archivos local. El parámetro mode especifica el modo de transferencia, ya sea FTP_ASCII o FTP_BINARY. El parámetro startpos especifica la posición en el archivo remoto desde la que comenzará la subida. Por defecto, startpos se establece en 0, lo que significa que la subida comenzará desde el inicio del archivo.

Uso de ftp_nb_fput()

Para usar la función ftp_nb_fput(), primero debes establecer una conexión al servidor FTP mediante la función ftp_connect() y autenticarte con ftp_login(). A continuación se muestra un ejemplo completo:

<?php

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

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

// Enable passive mode to prevent transfer issues
ftp_pasv($conn, true);

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

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

// Continue the asynchronous FTP operation
while ($res == FTP_MOREDATA) {
    $res = ftp_nb_continue($conn);
}

// Check for errors
if ($res != FTP_FAILED && $res != FTP_SUCCESS) {
    echo "FTP upload failed.\n";
}

// Close the file
fclose($handle);

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

En este ejemplo, establecemos una conexión al servidor FTP, iniciamos sesión con nuestras credenciales y habilitamos el modo pasivo con ftp_pasv() para evitar problemas comunes de transferencia detrás de firewalls. Abrimos el archivo local para lectura, luego llamamos a ftp_nb_fput() para iniciar la subida. El detalle clave es el bucle while: mientras ftp_nb_fput() (o las llamadas posteriores) devuelva FTP_MOREDATA, seguimos avanzando en la transferencia con ftp_nb_continue(). En una aplicación real, cada iteración de ese bucle es donde realizarías otro trabajo, ya que la transferencia es no bloqueante.

Manejo de errores en ftp_nb_fput()

Es importante manejar los errores correctamente cuando se usa la función ftp_nb_fput(). La función devuelve constantes específicas en lugar de un boolean, por lo que debes comprobar si hay FTP_FAILED para detectar errores. A continuación se muestra un ejemplo de cómo manejar errores:

<?php

// Assume $conn is already established and logged in
$handle = fopen('local_file.txt', 'r');
$res = ftp_nb_fput($conn, 'remote_file.txt', $handle, FTP_BINARY);

if ($res == FTP_FAILED) {
    echo "Failed to initiate upload.\n";
}

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

if ($res == FTP_FAILED) {
    echo "Failed to complete upload.\n";
}

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

Al manejar los errores de forma adecuada y comprobar las constantes de retorno tanto de ftp_nb_fput() como de ftp_nb_continue(), puedes garantizar el éxito de tus operaciones FTP.

ftp_nb_fput() frente a funciones relacionadas

PHP ofrece varias funciones de subida FTP. Elegir la correcta depende de si tienes un manejador de archivo abierto o solo una ruta, y de si necesitas comportamiento no bloqueante:

• ftp_fput() — sube desde un manejador de archivo abierto, bloqueando hasta terminar.
• ftp_put() — sube desde una ruta de archivo local, bloqueando hasta terminar.
• ftp_nb_put() — subida no bloqueante desde una ruta de archivo local (mismo patrón de bucle que esta función).
• ftp_nb_fput() — subida no bloqueante desde un manejador de archivo abierto (esta función).

Todas las variantes no bloqueantes comparten el mismo bucle FTP_MOREDATA / ftp_nb_continue().

Conclusión

La función ftp_nb_fput() sube un archivo a un servidor FTP en modo no bloqueante, permitiendo que tu script continúe ejecutando otras operaciones mientras la transferencia está en curso. El patrón esencial es: iniciar la subida, luego hacer un bucle con ftp_nb_continue() mientras el valor de retorno sea FTP_MOREDATA, y comprobar si hay FTP_FAILED en cada paso. Usada correctamente, mejora la capacidad de respuesta del código de transferencia de archivos en tus proyectos PHP.

Práctica