ftp_nb_put()

Entendiendo la función PHP ftp_nb_put()

La función ftp_nb_put() es una función integrada de PHP que sube un archivo a un servidor FTP usando el modo no bloqueante. "No bloqueante" significa que la llamada retorna inmediatamente después de iniciar la transferencia en lugar de esperar a que termine, de modo que tu script puede seguir realizando otras tareas mientras los bytes viajan por la red. Esta guía cubre sus parámetros, sintaxis, uso y manejo de errores para que puedas integrarla de forma efectiva en tus proyectos PHP.

La función complementaria es ftp_put(), que sube en modo bloqueante (el script se pausa hasta que la subida se completa). Utiliza ftp_nb_put() cuando quieras subir un archivo grande mientras muestras el progreso, procesas otras tareas o evitas una solicitud larga y congelada.

¿Qué es ftp_nb_put()?

La función ftp_nb_put() sube un archivo a un servidor FTP sin detener la ejecución del script. Acepta estos parámetros:

1. ftp_stream: El identificador de conexión devuelto por ftp_connect() (un objeto FTP\Connection en PHP 8.1+).
2. remote_file: La ruta del archivo remoto donde se subirá el archivo.
3. local_file: La ruta del archivo local desde donde se leerá.
4. mode: El modo de transferencia, ya sea FTP_BINARY o FTP_ASCII (obligatorio antes de PHP 7.3; opcional y con valor predeterminado FTP_BINARY a partir de 7.3).
5. startpos (opcional): El desplazamiento en bytes en el archivo remoto desde el que se comenzará a escribir; el valor predeterminado es 0.

A diferencia de una subida bloqueante, ftp_nb_put() no devuelve un simple true/false. En cambio, devuelve una de tres constantes enteras:

Debido a estos valores de retorno, ftp_nb_put() se usa casi siempre junto con ftp_nb_continue() en un bucle, como se muestra a continuación.

Sintaxis de ftp_nb_put()

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

Sintaxis de ftp_nb_put()

int ftp_nb_put ( FTP\Connection $ftp_stream , string $remote_file , string $local_file , int $mode [, int $startpos = 0 ] )

La función ftp_nb_put() toma tres parámetros obligatorios (ftp_stream, remote_file y local_file) y un parámetro opcional (startpos). El parámetro mode es obligatorio y especifica el modo de transferencia: FTP_BINARY se recomienda para la mayoría de los archivos (imágenes, archivos comprimidos, ejecutables) para evitar la corrupción de los finales de línea, mientras que FTP_ASCII se usa para archivos de texto plano (aunque FTP_BINARY es generalmente más seguro para todos los tipos de archivo). El parámetro startpos especifica la posición en el archivo remoto desde la que comenzar la subida. De forma predeterminada, startpos se establece en 0, lo que significa que la subida comenzará desde el principio del archivo.

Uso de ftp_nb_put()

Para usar la función ftp_nb_put(), primero estableces una conexión con ftp_connect() y te autenticas con ftp_login(). Luego inicias la subida y la impulsas hacia adelante en un bucle hasta que finalice:

Uso de ftp_nb_put()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die('Could not connect to FTP server.');
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die('Login failed.');
}

// Initiate an asynchronous FTP operation
$result = ftp_nb_put($conn, 'remote_file.txt', 'local_file.txt', FTP_BINARY);
if ($result === FTP_FAILED) {
    die('Upload failed.');
}

// 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);
}

if ($result === FTP_FINISHED) {
    echo "Upload completed successfully.\n";
}

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

En este ejemplo, nos conectamos al servidor FTP, iniciamos sesión con nuestras credenciales y comenzamos la subida con ftp_nb_put(). La primera llamada devuelve FTP_MOREDATA, así que entramos en un bucle y llamamos repetidamente a ftp_nb_continue() para enviar el siguiente bloque; el comentario // Do something else es donde actualizarías una barra de progreso o manejarías otras tareas. Cuando el bucle termina, comprobamos FTP_FINISHED para confirmar el éxito y luego cerramos la conexión con ftp_close().

Nota: Siempre llama a ftp_nb_continue() hasta que el resultado ya no sea FTP_MOREDATA. Si detienes antes, la subida quedará incompleta en el servidor.

Manejo de errores en ftp_nb_put()

Es importante manejar los errores correctamente al usar la función ftp_nb_put(). Si la función devuelve FTP_FAILED, significa que la subida no tuvo éxito. Aquí hay un ejemplo de cómo manejar los errores:

Manejo de errores en ftp_nb_put()

<?php

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

if ($result === FTP_FAILED) {
    echo "Failed to upload file to remote server.\n";
}

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

if ($result === FTP_FINISHED) {
    echo "Upload completed.\n";
}

ftp_close($conn);

Manejando los errores de forma adecuada y verificando el valor de retorno de la función, puedes asegurar el éxito de tus operaciones FTP usando la función ftp_nb_put().

Funciones relacionadas

• ftp_put() — sube un archivo en modo bloqueante (más simple, pero pausa el script).
• ftp_nb_continue() — continúa una transferencia no bloqueante iniciada por ftp_nb_put().
• ftp_nb_fput() — subida no bloqueante desde un manejador de archivo ya abierto en lugar de una ruta.
• ftp_nb_get() — el equivalente de descarga de ftp_nb_put().

Conclusión

La función ftp_nb_put() sube archivos a un servidor FTP en modo no bloqueante, permitiendo que tu script continúe con otras tareas mientras la transferencia se ejecuta en segundo plano. La clave es iniciar la subida, iterar sobre ftp_nb_continue() mientras el estado sea FTP_MOREDATA y confirmar FTP_FINISHED (manejando FTP_FAILED) antes de cerrar la conexión. Con un uso adecuado y un buen manejo de errores, es una herramienta valiosa para transferencias de archivos responsivas en tus proyectos PHP.

Nota: Las funciones ftp_nb_* se consideran heredadas en el PHP moderno. Para nuevos proyectos, considera usar cURL o una biblioteca HTTP asíncrona como Guzzle para mejor rendimiento, seguridad y soporte de protocolos más amplio.

Práctica