ftp_fput()

¿Qué es ftp_fput()?

La función ftp_fput() es una función integrada de PHP que sube un archivo al servidor FTP. La función acepta cinco parámetros:

1. ftp_stream: El identificador de conexión devuelto por la función ftp_connect().
2. remote_file: El nombre del archivo remoto al que se debe subir el archivo.
3. local_file: Un recurso de manejador de archivo abierto con fopen() que apunta al archivo local que se va a subir.
4. mode (opcional): El modo de transferencia (FTP_ASCII o FTP_BINARY). El valor predeterminado es FTP_ASCII.
5. startpos (opcional): La posición inicial en el archivo remoto para la carga. El valor predeterminado es 0.

La función devuelve un valor boolean. Si la función logra subir el archivo, devuelve true. De lo contrario, devuelve false.

Cuándo usar ftp_fput() en lugar de ftp_put()

ftp_put() recibe una ruta de archivo local como string y abre el archivo por ti. ftp_fput() recibe en su lugar un manejador de archivo ya abierto. Usa ftp_fput() cuando:

• Los datos que quieres subir no son un archivo normal en disco — por ejemplo, un flujo temporal creado con php://temp, o la salida de otro recurso que ya tienes abierto.
• Necesitas un control preciso sobre la posición de lectura (combinado con el parámetro startpos, puedes reanudar una carga interrumpida).
• Ya has abierto el manejador por otra razón y quieres evitar abrir el mismo archivo dos veces.

Si solo quieres subir un archivo existente por nombre, ftp_put() es más sencillo. Para cargas no bloqueantes (asíncronas), consulta ftp_nb_fput().

Sintaxis de ftp_fput()

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

Sintaxis de ftp_fput()

bool ftp_fput ( resource $ftp_stream , string $remote_file , resource $local_file [, int $mode = FTP_ASCII [, int $startpos = 0 ]] )

Uso de ftp_fput()

Para usar la función ftp_fput(), primero debes establecer una conexión al servidor FTP mediante la función ftp_connect(). Aquí tienes un ejemplo:

Uso de ftp_fput() en PHP

<?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.");
}

// Open the local file
$local_file = fopen('/local/directory/local_file.txt', 'r');
if (!$local_file) {
    die("Could not open local file.");
}

// Upload the file to the remote FTP server
if (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_ASCII)) {
    echo "File uploaded successfully.\n";
} else {
    echo "Failed to upload the file.\n";
}

// Close the file handle and FTP connection
fclose($local_file);
ftp_close($conn);

En este ejemplo, establecemos una conexión al servidor FTP mediante la función ftp_connect() y verificamos que se haya realizado correctamente. Luego iniciamos sesión con nuestras credenciales FTP usando ftp_login() y comprobamos si hay errores. A continuación, abrimos el archivo local con fopen() para obtener el manejador de archivo requerido. Finalmente, subimos el archivo al servidor FTP remoto usando ftp_fput() y cerramos tanto el manejador de archivo como la conexión FTP con ftp_close().

Elegir el modo de transferencia: FTP_ASCII vs FTP_BINARY

El parámetro mode controla cómo se transfieren los bytes y es más importante de lo que parece:

• FTP_BINARY transfiere el archivo byte a byte, sin cambios. Úsalo para imágenes, archivos comprimidos, ejecutables, PDFs — cualquier cosa que no sea texto plano. Este es el valor seguro predeterminado para casi todo.
• FTP_ASCII traduce los finales de línea entre las plataformas local y remota (por ejemplo, \n ↔ \r\n). Solo es apropiado para archivos de texto plano; usarlo con datos binarios corromperá el archivo silenciosamente.

Cuando abras el manejador local, ajusta el modo de fopen() a la transferencia: usa 'rb' (lectura binaria) junto con FTP_BINARY para que PHP no altere los bytes al leerlos:

<?php

$local_file = fopen('/local/directory/photo.jpg', 'rb');
ftp_fput($conn, 'photo.jpg', $local_file, FTP_BINARY);
fclose($local_file);

Manejo de errores en ftp_fput()

Es importante manejar los errores correctamente al usar la función ftp_fput(). Si la función devuelve false, significa que el archivo no pudo subirse por alguna razón. Aquí tienes un ejemplo de cómo manejar los errores:

Manejo de errores en ftp_fput()

<?php

// Assuming $conn is already established via ftp_connect() and ftp_login()
$local_file = fopen('/local/directory/local_file.txt', 'rb');

if ($local_file === false) {
    echo "Could not open the local file.\n";
} elseif (ftp_fput($conn, 'remote_file.txt', $local_file, FTP_BINARY)) {
    echo "File uploaded successfully.\n";
    fclose($local_file);
} else {
    echo "Failed to upload the file.\n";
    fclose($local_file);
}

Observa el orden de las comprobaciones: primero confirmamos que fopen() devolvió un manejador válido, luego llamamos a ftp_fput(). Llamar a fclose() sobre un manejador con valor false (lo que ocurre si el ejemplo original omite la comprobación de apertura) emite una advertencia, así que solo cerramos el manejador en las ramas donde realmente fue abierto. Esto evita que el mensaje de "éxito" se muestre cuando la carga no se produjo.

Errores comunes

• Pasar una ruta en lugar de un manejador. ftp_fput() espera el recurso devuelto por fopen(), no un string con el nombre del archivo. Si tienes una ruta, usa ftp_put() en su lugar.
• Modo de transferencia incorrecto. Subir un archivo binario con FTP_ASCII lo corrompe. Ante la duda, usa FTP_BINARY.
• No cerrar el manejador. Siempre llama a fclose() una vez terminada la transferencia para liberar el recurso.
• Modo pasivo. Detrás de un cortafuegos, muchos servidores requieren el modo pasivo. Llama a ftp_pasv($conn, true) después de iniciar sesión si las cargas se quedan bloqueadas.

Conclusión

La función ftp_fput() sube un archivo a un servidor FTP desde un manejador de archivo abierto, lo que la convierte en la opción adecuada cuando tus datos ya residen en un flujo en lugar de en una ruta fija en disco. Combínala con el modo de transferencia correcto, verifica los valores de retorno de fopen() y ftp_fput(), y cierra tus manejadores; así funcionará de manera confiable en tus proyectos PHP.

Práctica